Real-Time APIs · Webhooks
Webhook Reliability: Retries, Ordering and Replay
Make missed deliveries recoverable.
Webhooks will be missed: endpoints go down, deploys happen, bugs drop events. Senders should retry with backoff for days and expose an events API (GET /events?since=…) so consumers can reconcile and backfill. Consumers should periodically reconcile important state via the API rather than trusting webhooks alone. Document ordering guarantees (usually none) and recommend fetching the latest resource on each event.
Reliability mechanisms
| Mechanism | Who | Purpose |
|---|---|---|
| Retries with backoff (≈3 days) | Sender | Survive temporary outages |
| Delivery log + manual resend | Sender | Self-service recovery |
| Events/list API with cursors | Sender | Backfill and reconciliation |
| Periodic reconciliation job | Consumer | Catch anything missed |
| Endpoint auto-disable + email | Sender | Stop wasting retries; alert owner |
Retry schedule (example)
immediately → 5 s → 5 min → 30 min → 2 h → 5 h → 10 h → 10 h (≈ 27 h total, then mark failed)
Consumer backfill: GET /v1/events?type=invoice.paid&created_after=2026-10-10T00:00:00Z&cursor=…
Common pitfalls
- Webhooks as the only integration path (no backfill).
- Retrying forever against dead endpoints.
- Consumers never reconciling.
Key points
- Retries + logs + resend
- Events API for backfill
- Consumers reconcile periodically
Further reading: GitHub: Handling failed webhook deliveries
Practice questions
Why should webhook providers also offer an events API?
Answer
Consumers can recover missed events after outages and reconcile state, since webhooks alone can't guarantee delivery forever.
What should happen when an endpoint fails consistently for days?
Answer
Stop retrying (disable the endpoint), notify the owner, and let them resend or backfill via the events API after fixing it.
Open in the app to mark lessons complete, take notes and track your progress.