[
{
"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":"Billing",
"link":"https://docs.solidgate.com/billing/",
"text":"Smart billing solutions designed for diverse business models.",
"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
Solidgate uses webhooks to handle asynchronous events for payments, subscriptions, and chargebacks. This ensures you receive all necessary information.
A webhook uses your external application’s URL and sends HTTP requests when subscribed events occur.
Solidgate sends POST requests to your merchant endpoint with event details in the request body.
The merchant's server subsequently processes the incoming request, using its predefined business logic to handle information.
Manage webhooks
Solidgate offers webhooks to notify your system about various events, ensuring communication and providing a way to build automated workflows.
At the core of webhook configuration is the endpoint. It defines how and where events are delivered and includes the following:
Event types to receive
Destination URL for delivery
Identifier for event routing
Descriptive name for configuration
Endpoints are identified by:
url - the HTTP destination for webhook events
channel_id - the delivery channel identifier
This combination ensures webhook events are sent to the correct destination using the right channel.
Once the endpoints are set up, the event delivery process unfolds as follows:
A subscribed event occurs.
Solidgate sends an HTTP POST request to your webhook endpoint. The request includes event details and a unique signature for verification.
Solidgate expects your server to:
Process the webhook based on your business logic
Verify the event signature for security
Respond with a 2xx HTTP status code within 30 seconds
If no valid response is received in time, Solidgate retries the delivery.
You can configure webhooks in the Developer section of the
Solidgate
HUB
by adding different endpoints for each event type.
This setup allows flexible notification management.
For the endpoint setup, you need to:
Set up an endpoint on your server to receive webhook notifications from Solidgate.
Add the endpoint in the Solidgate HUB with the handler URL and your specified events.
To add an endpoint in HUB
Go to Developers > Channels.
Find the needed channel and click on it.
On the Channel details page, go to the Webhooks section.
Click on Add endpoint.
In the pop-up window, set up the endpoint:
Select the events you want to subscribe to.
Enter the URL for event delivery.
Click Add to confirm.
The endpoint is created in the active status. You can edit, deactivate, or delete it if needed.
Card payments
Available event types include:
Updated card order
Webhook Provides secure, real-time updates on card order status, enabling automated responses to changes.
Received dispute
Webhook Provides chargeback notifications, enabling automated updates upon receipt of a new dispute for a card order.
Created network token
Webhook Provides the creation of a network token by Visa Token Service, Mastercard Digital Enablement Service or Secure Card on File.
Updated network token
Webhook Provides updates on network tokens, enabling immediate system adjustments and reflecting changes in their status.
Received prevention alert
Webhook Provides card alerts for chargeback risks, indicating the reception of an issuer network alert to enhance dispute resolution.
Received fraud alert
Webhook Provides fraud alerts, denoting the acquisition of a TC40/SAFE alert to help merchants take swift preventive actions.
Available events include:
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 dispute 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
Available event types include:
Updated alternative order
Webhook Provides secure notifications for alternative payment methods, representing updates on the status of an alternative order.
Received PayPal dispute
Webhook Provides updates on the creation and progression of PayPal disputes, offering critical insights into their lifecycle.
Received prevention alert
Webhook Provides APM alerts for chargeback risks, indicating the reception of an issuer network alert to enhance dispute resolution.
Available events include:
Updated alternative order Provides secure notifications for alternative payment methods, representing updates on the status of an alternative order.
Received PayPal dispute Provides updates on the creation and progression of PayPal disputes, offering critical insights into their lifecycle.
Received dispute prevention alert Provides APM alerts for chargeback risks, indicating the reception of an issuer network alert to enhance dispute resolution.
Subscription
Available event types include:
Subscription updates
Webhook Provides subscription updates, including initiation and modification events, highlighting subscription or related order status changes.
Available events include:
Subscription updates Provides subscription updates, including initiation and modification events, highlighting subscription or related order status changes.
Taxes
Available event types include:
Calculated tax
Webhook Provides notifications about tax calculations for transactions, delivering key details like calculated amounts and tax type breakdowns, ensuring merchants have accurate and accessible tax information.
Available events include:
Calculated tax Provides notifications about tax calculations for transactions, delivering key details like calculated amounts and tax type breakdowns, ensuring merchants have accurate and accessible tax information.
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 refers to the payload sent 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 special characters, whitespace, or escape sequences remain unchanged during signature generation. Processing JSON through URL-encoding or serializers may alter the SHA-512 hash output. This results in different signatures.
Double-check that the jsonString used for signature generation matches the body received in the API request without alterations.
Ensure that data passed into the generateSignature function retains its original structure and format to preserve data integrity.
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, and it is not necessary to additionally verify the content of the request body.
The unique event ID of each action, provided in the request header parameters, is crucial for monitoring and managing webhook events.
Field
Description
Example
solidgate-event-id
Unique event ID, an identifier for monitoring and managing webhook events.
e1765cf7-70f7-4e56-8fb2-bd88744a94d1
Handle 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 webhook, for about a minute, to collect all relevant data. For TTL, store processed solidgate-event-id for up to a week to cover potential duplicates and ensure efficient handling of events.
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.