Idempotent webhook handling: delivery IDs, provider retry schedules and responding fast

What it is

Every provider names a field to deduplicate on, but the retry behaviour behind it is not interchangeable. GitHub's delivery ID (X-GitHub-Delivery) identifies a delivery, and "if you request a redelivery, the X-GitHub-Delivery header will be the same as in the original delivery." GitHub's docs also state plainly: "GitHub does not automatically redeliver failed webhook deliveries, but you can handle failed deliveries manually or by writing code" — a receiver that misses a delivery (including any response slower than 10 seconds) must notice it and trigger a redelivery through the UI or REST API, which only reaches recent deliveries (GitHub's pages currently state both 3 and 7 days). Stripe is the opposite: its webhook guide warns that "webhook endpoints might occasionally receive the same event more than once," recommends logging processed event IDs (and, for the rare case of two separate Event objects, deduplicating on data.object id plus event.type), and documents automatic retries "for up to three days with an exponential back off in live mode" (three retries over a few hours in a sandbox); manual resends work for up to 15 days in the Dashboard and 30 days via the CLI. Slack's Events API retries "a failed request up to 3 times in a gradually increasing timetable" — nearly immediately, then after 1 minute, then after 5 minutes — and tags each attempt with an x-slack-retry-num header (1, 2 or 3) and an x-slack-retry-reason header explaining why (http_timeout, http_error, and so on); a non-2xx response carrying x-slack-no-retry: 1 stops further attempts. The Standard Webhooks specification recommends exactly this pattern generically: "Use the webhook-id header as an idempotency key to prevent accidentally processing the same webhook more than once (e.g. save the IDs in redis for 5 minutes)."

Why it matters

Processing the same event twice can double-charge, double-notify or double-mutate state; a retry policy you don't know about (or a missing one you assumed existed) either causes duplicate side effects or silently drops events.

How to apply

• Persist processed identifiers (delivery ID, event ID, or webhook-id) with an expiry at least as long as the provider's redelivery window — at least 7 days for GitHub, 3 days for Stripe's automatic retries (up to 30 days if anyone resends manually), and more than the roughly six-minute retry span for Slack.
• Acknowledge fast (2xx within 10 seconds for GitHub, within 3 seconds for Slack, "quickly" for Stripe) and do side-effecting work after the acknowledgement, in a queue, so a slow downstream call cannot cause a provider-side timeout that triggers an unwanted retry.
• For GitHub specifically, do not assume a missed or failed delivery will ever arrive again on its own; build monitoring or a scheduled re-fetch of recent deliveries.
• Read a provider's retry-reason header (where offered, like Slack's) into your logs; it tells you whether the receiver or the network caused the retry.

Pitfalls

Deduplicating on a hash of the payload instead of the provider's identifier — payloads can legitimately repeat (two identical low-value transactions) while IDs never do. Assuming Stripe's or Slack's retry window is short enough that an in-memory, per-process dedup cache is sufficient; a restart between retries loses the record.