In Solidgate, asynchronous events for payments, subscriptions, and chargebacks are handled 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.

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

Event subscription

Sets up an endpoint on the server where Solidgate will send webhook notifications.

Card payments

Alternative payments

Subscription

Taxes

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:

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 key wh_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.

• 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.

1
2
3
4
5
6

public function generateSignature ($ data)
{
  return base64_encode (
  hash_hmac ('sha512', $ wh_pk. $ data. $ wh_pk, $ wh_sk_)
  );
}

Event handling

Occasionally, you may receive duplicate events during notification retries or when resending requested events. To mitigate this, consider implementing idempotent processing in your integration.

The unique event ID of each action, provided in the request header parameters, is crucial for monitoring and managing webhook events.

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.

By following these best practices, merchants can effectively manage non-ordered events in webhooks, which ensures accurate and reliable event processing in their systems.