Webhook Retry Logic
Webhook retry logic refers to the strategy a webhook provider uses to re-attempt delivery of an event payload when the initial HTTP request fails or the consumer returns a non-2xx status; Providers typically retry with exponential backoff: the first retry fires after seconds, subsequent retries after minutes, and final retries after hours or days; Consumer endpoints that process webhook events synchronously, such as running a slow database write before returning 200, are a common cause of apparent delivery failures
Webhook retry logic refers to the strategy a webhook provider uses to re-attempt delivery of an event payload when the initial HTTP request fails or the consumer returns a non-2xx status. Robust retry logic is essential because consumer endpoints may be temporarily unavailable due to deployments, network partitions, or overload.
How it works
Providers typically retry with exponential backoff: the first retry fires after seconds, subsequent retries after minutes, and final retries after hours or days. The total retry window varies by provider (for example, Stripe retries for up to 72 hours). Because the same event can be delivered multiple times, consumer endpoints must be idempotent.
Key facts
- Exponential backoff: Retry intervals grow geometrically (1s, 2s, 4s, 8s) to reduce thundering herd on recovery
- Idempotency requirement: Consumers must handle the same event ID arriving multiple times without duplicate processing
- Dead-letter queue: Events that exhaust retries should be captured for manual inspection and replay
For builders
Consumer endpoints that process webhook events synchronously, such as running a slow database write before returning 200, are a common cause of apparent delivery failures. Accept the webhook immediately, enqueue it, and process asynchronously.
Sources
- IETF. RFC 9110: HTTP Semantics. datatracker.ietf.org
- IETF. RFC 9112: HTTP/1.1. datatracker.ietf.org
- Fielding, R. (2000). Architectural Styles and the Design of Network-based Software Architectures (REST). UC Irvine. ics.uci.edu
- OWASP. API Security Top 10 (2023). owasp.org
- MDN Web Docs. HTTP reference. developer.mozilla.org
