Webhooks
Retries & idempotency
Webhook deliveries are at-least-once. Your consumer must be idempotent and tolerant of out-of-order arrivals.
At-least-once delivery
Webhook deliveries are at-least-once. Your consumer must be idempotent and tolerant of out-of-order arrivals.
Delivery model
- Non-2xx triggers retry with exponential backoff.
- Backoff schedule scales over hours, not seconds, design for delay tolerance.
- Duplicate delivery of the same event ID can occur.
- Deliveries that exhaust retries are marked dead-letter for operator investigation.
Consumer pattern
Store processed webhook event IDs in durable storage. Ignore duplicates by event ID before side effects. Make downstream operations idempotent by your own business key.
- Persist event_id with a unique constraint.
- On replay, short-circuit before mutating state.
- Acknowledge with 2xx as soon as the work is durably recorded.
- Move heavy work to a background queue, keep the webhook handler fast.
Debugging failed deliveries
Use the deliveries endpoint to inspect recent attempts. Each delivery record exposes the request, response code, and the body your endpoint returned.
- Filter deliveries by endpoint and status.
- Replay failed deliveries from the console once the consumer is patched.
- Set alerts on rising 5xx delivery rate per endpoint.
- Create runbooks for retries and partial incident handling.