In Solidgate, asynchronous events for payments, subscriptions, and chargebacks are facilitated through webhooks, ensuring our clients receive all the necessary information. A webhook consists of a URL provided by the external application, and the payment system sends an HTTP request to that URL when a subscribed event occurs. Solidgate then sends a POST request to the merchant’s endpoint, containing event details in the request body.
Here are the general steps on how webhooks work in Solidgate:
- The merchant establishes an endpoint on their server for Solidgate to send webhook notifications.
- Register merchant’s webhook handler in the administrative HUB system. You will need to provide the URL of your handler and select the event types you would like to subscribe to.
- Upon the occurrence of a subscribed event, Solidgate dispatches an HTTP POST request containing event details to the merchant’s endpoint.
- The merchant’s server obtains and processes the request based on their established business logic.
- The merchant’s server returns an HTTP response to Solidgate, confirming the webhook’s receipt and processing.
It’s important to note that the merchant should ensure that the endpoint is always available and can handle incoming requests promptly to avoid missing any important notifications.
Receive webhooks
Webhooks can be managed within the Solidgate HUB by navigating to the channel settings located in the developer section.
Configure webhooks
It is feasible to configure up to 20 distinct endpoints for receiving the following event types:
- Updated Card Order - reflects a change in the status of a card order
- Updated Alternative Order - represents an update in the status of an alternative order
- Updated Subscription - highlights a modification in the subscription or related order status
- Received Card Chargeback - indicates the receipt of a new dispute for the card order
- Received Card Prevent Alert - signifies the reception of an Issuer Network alert
- Received Card Fraud Alert - denotes the acquisition of a TC40/SAFE alert
Receive events
Should you opt to receive identical events across multiple endpoints, webhook notifications will be dispatched to all specified endpoints.
Event types
Below is a list of events you can receive to automate your system, each accompanied by a unique signature for identifying Solidgate transactions in accordance with the API access rules.
-
Card order status Webhook
Allows merchants to securely receive real-time card order status updates (e.g.,processing
ordeclined
) and automatically initiate relevant actions or system changes. -
Alternative payment methods order status Webhook
Enables secure, real-time notifications for alternative payment methods (statusprocessing
ordeclined
), allowing merchants to autonomously respond and update their systems. -
Subscription status Webhook
This webhook adds a callback type parameter with four options:init
,renew
,update
, andcancel
-
Chargeback Webhook
Enables secure real-time chargeback event notifications for merchants, allowing automated system actions or updates based on these events. -
Prevent alert Webhook
Offers secure, real-time chargeback notifications for merchants, enabling prompt dispute resolution and loss minimization. -
Fraud alert Webhook
Enables secure, real-time fraud alerts for merchants, facilitating swift action to prevent losses.
Delivery attempts
If the webhook notification fails due to an incorrect response, the retry mechanism will automatically attempt to resend it multiple times.
We will attempt to deliver notifications according to the following structured schedule:
- 15 minutes after the initial failed notification
- 30 minutes after the first failed retry
- 1 hour after the second failed retry
- 2 hours after the third failed retry
- 4 hours after the fourth failed retry
- 8 hours after the fifth failed retry
- 16 hours after the sixth failed retry
- 24 hours after the seventh failed retry
Security
Webhook event security is handled similarly to API authentication. In each notification, you will receive the Merchant ID and Signature value in the headers.
- The Merchant ID corresponds to the webhook public key
wh_pk_
- The Signature value is calculated using the webhook public and secret keys, which helps verify the authenticity and integrity of the webhook data transmitted between Solidgate and the merchant’s server.
You need to retrieve the merchant (wh_pk_
) from the request headers and verify if you possess the corresponding credentials.
Generate a signature from the received body using the generateSignature
function, as you would when sending a request to a gateway.
|
|
Event handling
Occasionally, you may receive duplicate events, which can occur during notification retries or when resending requested events.
We recommend implementing idempotent processing in your integration to prevent the negative effect of duplicate events.
The unique event ID for each action is provided in the request header parameters, as outlined below:
Header | Description | Example |
---|---|---|
solidgate-event-id |
Unique event ID: a crucial identifier for monitoring and managing webhook events. | e1765cf7-70f7-4e56-8fb2-bd88744a94d1 |
Related articles FAQ