Webhooks

Register your system to receive notifications

The Webhook API enables developers to subscribe to notifications for changes of selected events. This API allows you to register a webhook to send notifications to any specified URL, update the URL as needed, or unsubscribe from notifications entirely.

All notifications are secured with an HMAC signature (SHA256) included in the X-Signature header, allowing recipients to verify the authenticity of each message.

The secretKey used for generating the HMAC signature is provided in the response upon successful webhook registration.

Message example

All messages follow this payload format. The data parameter contains an object with all information about the given entity. For order updates, the format is Get Order Details.

{
    "event": "ORDER_STATUS_UPDATED",
    "timestamp": "2025-07-08T12:34:56Z",
    "data": {
        ...
    }
}

How to verify message authenticity

By following this process, you ensure that your system only processes verified notifications for any subscribed event and remains secure against tampered or fraudulent requests.

1. Webhook Registration

Subscribe to new event notifications by using the endpoint Register new Webhook

In response, you will receive a secretKey, which you will use to verify the authenticity of each incoming notification.

2. Receiving Notifications

Whenever the selected event occurs, the system will automatically send a POST request to your specified URL, which includes:

• A JSON payload with the event data

• The X-Signature HTTP header containing an HMAC-SHA256 signature

3. Verifying the Signature

To ensure the notification is genuine and unaltered, follow these steps:

• Use the secretKey provided during the webhook registration.

• Compute the HMAC-SHA256 signature using the raw JSON request body.

Example in Node.js using crypto library

const crypto = require('crypto');

// secretKey from webhook registration
const hmac = crypto.createHmac('sha256', secretKey);

// rawRequestBody is the original JSON string (raw body of the request)
hmac.update(rawRequestBody);

const computedSignature = hmac.digest('hex');

4. Signature Comparison

• Compare your computed computedSignature with the value received in the X-Signature header (specifically the part after sha256=).

• If both signatures match, you can trust the notification as authentic.

Retry mechanism

If a notification cannot be delivered (e.g., due to a 4xx/5xx status code or a timeout), the system will automatically retry sending it using an exponential backoff strategy — the delay between attempts doubles each time (1s, 2s, 4s, 8s, etc.) and the maximum retry window is 24 hours.

The order of message delivery is guaranteed, ensuring that users receive their messages in the sequence they expect. A recipient will not receive another message for the same event until the previous one has been successfully received.