[
{
"title":"Testing",
"link":"https://docs.solidgate.com/payments/testing/",
"text":"Simulate payments to test your integration before launching in production.",
"imgSrc":"https://solidgate.com/wp-content/uploads/2022/06/icon-customizable.svg"
}
,
{
"title":"Create your payment form",
"link":"https://docs.solidgate.com/payments/integrate/payment-form/create-your-payment-form/",
"text":"Understand how to integrate the payment form into your product.",
"imgSrc":"https://solidgate.com/wp-content/uploads/2022/06/icon-payments.svg"
}
,
{
"title":"Subscriptions",
"link":"https://docs.solidgate.com/subscriptions/",
"text":"Create and maintain a stable and healthy business subscription model.",
"imgSrc":"https://solidgate.com/wp-content/uploads/2022/06/icon-global.svg"
}
]
Subscribe for events on your Solidgate account so your integration can automatically trigger actions
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.
The merchant's server subsequently processes the incoming request, using its predefined business logic to handle the information.
Manage webhooks
Solidgate offers merchants a way to build automated workflows by activating webhook notifications for various events. To use webhooks, merchants need to set up their endpoint and event subscriptions in the Solidgate HUB or via API.
Endpoint setup
Sets up an endpoint on the server where Solidgate is expected to send webhook notifications.
Registers this endpoint in the Solidgate HUB by providing the handler URL and selecting the specific events they wish to subscribe to.
Event subscription
Solidgate sends an HTTP POST request with event details to the merchant’s specified endpoint when a subscribed event occurs.
The server processes the request based on its predefined business logic.
The server should then respond with a 2xx HTTP status code to acknowledge the receipt and processing of the webhook. This response must be provided within 30 seconds to avoid failure and subsequent resending attempts by Solidgate.
Sets up an endpoint on the server where Solidgate will send webhook notifications.
Via API
This method enables automation by providing a list of events, each marked with a unique signature, to verify Solidgate transactions.
Merchants can set up their servers to handle these events, ensuring secure reception and processing of notifications.
Via HUB
Merchants can configure webhooks in the Solidgate HUB on the Channel details page of the Developer section.
HUB allows merchants to add different endpoints for each event type, offering greater flexibility in managing notifications.
Card payments
Order status
Webhook Provides secure, real-time updates on card order status, enabling automated responses to changes.
Chargeback
Webhook Provides chargeback notifications, enabling automated updates upon receipt of a new dispute for a card order.
Network token created
Webhook Provides the creation of a network token by Visa Token Service, Mastercard Digital Enablement Service or Secure Card on File.
Network token updated
Webhook Provides updates on network tokens, enabling immediate system adjustments and reflecting changes in their status.
Prevent alert
Webhook Provides card alerts for chargeback risks, indicating the reception of an issuer network alert to enhance dispute resolution.
Fraud alert
Webhook Provides fraud alerts, denoting the acquisition of a TC40/SAFE alert to help merchants take swift preventive actions.
Updated card order Provides secure, real-time updates on card order status, enabling automated responses to changes.
Received card dispute Provides chargeback notifications, enabling automated updates upon receipt of a new dispute for a card order.
Created card network token Provides the creation of a network token by Visa Token Service, Mastercard Digital Enablement Service or Secure Card on File.
Updated card network token Provides updates on network tokens, enabling immediate system adjustments and reflecting changes in their status.
Received card prevention alert Provides card alerts for chargeback risks, indicating the reception of an issuer network alert to enhance dispute resolution.
Received card fraud alert Provides fraud alerts, denoting the acquisition of a TC40/SAFE alert to help merchants take swift preventive actions.
Alternative payments
Order status
Webhook Provides secure notifications for alternative payment methods, representing updates on the status of an alternative order.
Prevent alert
Webhook Provides APM alerts for chargeback risks, indicating the reception of an issuer network alert to enhance dispute resolution.
Updated alternative order Provides secure notifications for alternative payment methods, representing updates on the status of an alternative order.
Received card prevention alert Provides APM alerts for chargeback risks, indicating the reception of an issuer network alert to enhance dispute resolution.
Subscription
Subscription status
Webhook Provides subscription updates, including initiation and modification events, highlighting subscription or related order status changes.
Subscription updates Provides subscription updates, including initiation and modification events, highlighting subscription or related order status changes.
Delivery attempts
If the webhook notification fails due to an incorrect response, the retry mechanism automatically makes several attempts to resend it.
Notification delivery attempts follow the structured schedule below:
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 receive the
Guide
Learn to authenticate API requests and generate signatures.
merchant
and
Guide
Learn to authenticate API requests and generate signatures.
signature
values in the headers.
merchant value corresponds to the webhook
Guide
Learn to authenticate API requests and retrieve your credentials.
public keywh_pk_
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
The data variable within the generateSignature function pertains to the payload transmitted via the webhook. This data can include event-related information, like order events, and is sent by Solidgate as part of the triggering HTTP request body.
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.
When generating a signature, it is essential to use the raw JSON data exactly as it is received in the body of the API request. Avoid any modifications or processing through serializers, as these can alter the structure of the data, leading to signature mismatches.
For example, ensure that special characters, whitespace, or escape sequences remain unchanged during the signature generation process. If the JSON is processed (e.g., URL-encoded or formatted by a serializer), it may alter the output of the SHA-512 hash, resulting in a different signature.
Verify Raw JSON input: Double-check that the jsonString used for signature generation matches the body received in the API request without alterations.
Preserve Data integrity: When generating the signature, ensure that data passed into the generateSignature function retains its original structure and format.
Occasionally, you may receive duplicate events during notification retries or when resending requested events. To mitigate this, consider implementing idempotent processing in your integration.
This approach helps prevent the negative effects of duplicate events.
Each action’s unique event ID, provided in the request header parameters, is crucial for monitoring and managing webhook events.
Header
Description
Example
solidgate-event-id
Unique event ID, an identifier for monitoring and managing webhook events.
e1765cf7-70f7-4e56-8fb2-bd88744a94d1
Handling non-ordered events
In Solidgate, webhooks are essential for asynchronous event communication, such as payments, subscriptions, and chargebacks. However, the order of received webhook events may not always match the sequence of their occurrence. This section offers guidance on effectively managing non-ordered events.
Non-sequential delivery
The delivery order of webhooks is not guaranteed. Relying solely on the sequence of event occurrence when processing webhooks could lead to inaccuracies in event handling.
Asynchronous event processing Implement a queue-based approach for processing incoming events, rather than handling them synchronously.
This is crucial due to the timeout constraints on webhook sending. Synchronous processing that exceeds the timeout limit may lead to webhooks being marked as undelivered, which can complicate the order of event processing.
Accumulating webhooks Temporarily store incoming webhooks (e.g., for about a minute) before processing. This delay allows for the collection of all relevant webhooks, aiding in more accurate event processing.
Handling event collisions In cases where an event cannot be processed due to insufficient data, often resulting from delayed delivery of some events, use the Solidgate API to retrieve the necessary information.
By following these best practices, merchants can effectively manage non-ordered events in webhooks, which ensures accurate and reliable event processing in their systems.