Webhook Integration Guide
Version 1.2 — Last updated July 2026
1. Overview
This guide explains how to configure your application to receive and verify webhook events. Webhooks
let your server receive real-time notifications when events occur, such as a payment succeeding or a
subscription being cancelled, without needing to poll an API.
2. Prerequisites
Before you begin, you will need: a publicly reachable HTTPS endpoint capable of accepting POST
requests, an account with an active API key, and the ability to read response headers on incoming
requests.
3. Registering an Endpoint
Register your endpoint URL from the dashboard under Settings > Webhooks > Add Endpoint. Select the
event types you want to subscribe to. Upon registration, you will receive a signing secret; store this
securely, as it is used to verify that incoming requests genuinely originate from our servers.
4. Event Payload Format
Each webhook is delivered as a JSON POST request with the following structure:
{
"id": "evt_1a2b3c",
"type": "[Link]",
"created": 1719878400,
"data": {
"amount": 4200,
"currency": "usd",
"customer_id": "cus_9f8e7d"
}
}
5. Verifying Signatures
Every request includes an X-Signature header containing an HMAC-SHA256 hash of the raw request
body, computed using your signing secret. Always verify this signature before processing the payload,
and always use a constant-time comparison function to prevent timing attacks.
Example ([Link])
const crypto = require('crypto');
function verifySignature(rawBody, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest('hex');
Page 1 of 2
return [Link](
[Link](signature),
[Link](expected)
);
}
6. Responding to Webhooks
Your endpoint should respond with a 2xx status code within 10 seconds to acknowledge receipt. Any
other response, or a timeout, is treated as a delivery failure. Avoid performing slow, synchronous
processing inside the webhook handler itself; instead, acknowledge receipt immediately and process the
event asynchronously in a background job.
7. Retry Behavior
Failed deliveries are retried using exponential backoff for up to 24 hours: immediately, then after 5
minutes, 30 minutes, 2 hours, 6 hours, and 24 hours. After the final attempt fails, the event is marked as
undelivered and can be manually redelivered from the dashboard.
8. Idempotency
Because retries can occasionally result in duplicate deliveries, your handler should be idempotent. Use the
event id field to track which events have already been processed, and skip processing for any id you have
seen before.
9. Testing Locally
Use the provided CLI tool to forward events to a local development server:
$ webhook-cli listen --forward-to localhost:4000/webhooks
> Ready! Listening for events...
> [Link] -> 200 OK (142ms)
10. Troubleshooting
If you are not receiving events, first confirm the endpoint is publicly reachable and returns a 2xx response
for a manual test event, sent from the dashboard's “Send test event” button. If signatures fail to verify,
confirm you are hashing the raw, unparsed request body rather than a re-serialized version of the parsed
JSON, since re-serialization can alter whitespace and break the hash comparison.
Page 2 of 2