2xx response within 10 seconds, we retry on an exponential backoff schedule.
Retry schedule
After 4 failed attempts the webhook is marked as failed. You can manually retry from the webhook deliveries page in the dashboard. Failed deliveries keep the request payload and your endpoint’s response so you can inspect them before retrying; successful deliveries keep the event, the HTTP status and the time.
Endpoints that keep failing
An endpoint that fails every delivery for 3 days in a row, with no successful delivery in that time, is turned off automatically. Your organization’s owners and admins get one email naming the endpoint, its URL, and the date the failures began, and the endpoint shows Disabled after repeated failures under Admin > API > Webhooks. To turn it back on, fix the URL or the server behind it so it answers with a2xx, then choose Re-enable on the endpoint. Its failure record starts fresh.
Best practices
Return 200 within 10 seconds
Return 200 within 10 seconds
Process asynchronously if needed. Queue the event for background processing and return
200 immediately. This prevents retries on slow handlers.Always validate the HMAC signature before processing
Always validate the HMAC signature before processing
See Signature Validation.
Use event_id to deduplicate
Use event_id to deduplicate
Rare but possible - under network failure conditions you could receive the same event twice. Store processed
event_ids and skip duplicates.Log failures and monitor endpoint health
Log failures and monitor endpoint health
Set up alerting on failed webhook deliveries. The deliveries page in the dashboard and your own application logs together give you full traceability.
Use HTTPS endpoints (required in production)
Use HTTPS endpoints (required in production)
HTTPS is enforced for all production webhook endpoints. Self-signed certs are not accepted - use a real CA-issued cert.
Rotate secrets periodically (every 90 days recommended)
Rotate secrets periodically (every 90 days recommended)
From the dashboard, regenerate the signing secret on each endpoint. Update your application’s environment variable, then verify a test webhook validates with the new secret before relying on it.