Webhooks
Retries & idempotency
Webhook deliveries are at-least-once. Your consumer must be idempotent and tolerant of out-of-order arrivals.
Delivery model
- 2xx from your endpoint marks delivery successful.
- Non-2xx triggers retry with backoff.
- 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.
- Acknowledge quickly; push expensive work to async jobs.
Debugging failed deliveries
GET
/v1/webhooks/deliveriesList delivery attemptsGET
/v1/webhooks/deliveries/{deliveryId}Inspect one deliveryPOST
/v1/webhooks/deliveries/{deliveryId}/resendResend failed/dead-letter deliveryThese endpoints help you inspect response codes and retry history when your endpoint is not acknowledging events.
Use resend from your dashboard when a delivery is in FAILED or DEAD_LETTER. Delivered or in-progress deliveries cannot be resent.
Ordering
Do not assume strict ordering across different event types. Use resource-level timestamps/version checks where ordering matters.
For event subscription configuration, see /business/docs/webhooks.