What Is a Webhook?
A webhook is an HTTP callback that sends real‑time data from our platform to a URL you provide. Whenever a subscribed event occurs, we POST a JSON payload to your endpoint.
- Push‑based: No polling required.
- Lightweight: Small JSON bodies, simple HTTP.
- Secure: HMAC signatures and TLS.
Core Concepts
Endpoints
Your endpoint must accept POST requests with a Content‑Type: application/json header. The response should be 200 OK within 2 seconds.
Payload Structure
{
"event": "order.created",
"timestamp": "2025-09-17T12:34:56Z",
"data": {
"order_id": "ORD_12345",
"total": 199.99,
"currency": "USD"
}
}Signature Verification
Each request includes an X‑Webhook‑Signature header. Compute an HMAC‑SHA256 hash of the raw request body using your secret and compare it to the header value.
Getting Started
- Register a webhook URL in your Setup Guide.
- Select the events you want to receive.
- Implement an endpoint that validates the signature and returns
200. - Test using the Webhook Tester.
Common Issues & Fixes
Timeout (504)
Ensure your endpoint processes the request and returns a response within 2 seconds. Offload heavy work to background jobs.
Signature Mismatch
Verify that you are using the exact secret provided and that the request body is not altered (no whitespace changes).
Invalid JSON
Use a JSON parser that tolerates UTF‑8 and validates against the schema described in the Event Catalog.
FAQ
Can I send webhooks to multiple URLs?
Yes. Register each URL as a separate webhook subscription.
What retry policy is used?
We retry up to 5 times with exponential back‑off (1 min, 5 min, 15 min, 30 min, 60 min). After the final failure the event is marked as undeliverable.
Do I receive a test payload?
When you create a webhook, a test ping event is sent immediately.