Webhooks

Webhooks allow your application to receive real-time notifications from our service when specific events occur. Instead of constantly polling our API, you can set up a webhook endpoint that our service will send an HTTP POST request to whenever an event you've subscribed to happens.

How Webhooks Work

1. Subscription: You register your webhook URL and specify the events you want to receive notifications for.
2. Event Trigger: When a subscribed event occurs in our system, we generate a payload containing event details.
3. Delivery: We send an HTTP POST request with the event payload to your registered webhook URL.
4. Acknowledgement: Your application should respond with an HTTP 2xx status code (e.g., 200 OK) to acknowledge receipt of the webhook. Failure to do so may result in retries or eventual deactivation of the webhook.

Security Considerations

Verifying Signatures

Each webhook request includes an X-Webhook-Signature header. This signature is generated by hashing the request body using your webhook's secret key (which you obtain during webhook setup) and a specific algorithm (e.g., SHA256). To verify:

1. Retrieve your webhook secret key.
2. Concatenate the timestamp (from the X-Webhook-Timestamp header) and the request body.
3. Compute the HMAC-SHA256 hash of the concatenated string using your secret key.
4. Compare the computed hash with the value of the X-Webhook-Signature header. If they match, the request is authentic.

// Example using Node.js with crypto
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret, timestamp) {
    const hmac = crypto.createHmac('sha256', secret);
    hmac.update(`${timestamp}.${payload}`);
    const expectedSignature = hmac.digest('hex');
    return signature === expectedSignature;
}
            

Available Events

We currently support the following events:

{ "event": "user.created", "data": { "user_id": "usr_abc123", "email": "test@example.com" } }

{ "event": "order.placed", "data": { "order_id": "ord_xyz789", "user_id": "usr_abc123", "amount": 99.99 } }

{ "event": "payment.completed", "data": { "payment_id": "pay_def456", "order_id": "ord_xyz789", "status": "completed" } }

Webhook Request Structure

All webhook POST requests will have the following JSON structure:

{
  "event": "string", // The name of the event
  "data": {
    // Object containing event-specific data
  },
  "created_at": "ISO8601 Timestamp" // When the event occurred
}
            

Headers

Webhook requests will include the following important headers:

• Content-Type: application/json
• X-Webhook-Signature: string: The signature used for verification.
• X-Webhook-Timestamp: string: The Unix timestamp when the event was generated.
• X-Request-Id: string: A unique identifier for the webhook delivery attempt.

Setting Up a Webhook

You can configure your webhooks through the Developer Dashboard.

When setting up a webhook, you will need to provide:

• URL: The endpoint on your server that will receive the POST requests. This URL must be publicly accessible.
• Events: A list of events you wish to subscribe to.
• Secret Key: A unique secret key will be generated for your webhook. Store this securely, as it's used for signature verification.

Handling Retries and Failures

If your endpoint returns an error status code (non-2xx) or does not respond within a reasonable timeout, we will attempt to redeliver the webhook. We typically retry failed deliveries for a limited period.

To prevent duplicate processing, ensure your webhook handler is idempotent. This means processing the same webhook multiple times should have the same effect as processing it once.