Why Webhook Retries Can Overload Struggling Receivers
A webhook is an HTTP request that one service sends to another when an event occurs, such as a payment update or…
Categories
Documenting Webhook Failure Recovery in API References
When an API provider sends a webhook, its recovery documentation tells customers what happens if the notification does not reach their server and how to recover the missed information. A webhook is an HTTP request that tells a server about an event, such as a change to a resource. A delivery attempt is one try to send that request. If the customer’s server does not accept or process it, the customer needs to know whether the provider will try again. They also need to know where to find the failed attempt and which recovery options remain.
A useful reference explains how the provider marks an attempt as failed, whether it retries automatically, how customers find the failed attempt and request another delivery, and how long the provider keeps the records. It also explains what customers can do after those windows expire. These details help customers recover missed events while making clear that some events may never arrive.
Define what counts as a failed delivery
State the exact conditions that mark a delivery attempt as failed. Explain how the provider handles HTTP response codes. Also describe what happens when a connection fails or a request times out, along with any other relevant results. If the provider considers a particular response range successful, say so directly. For example, Shopify’s webhook troubleshooting guidance explains how response outcomes affect delivery status.
Explain what a successful response means. The provider typically treats the response it receives as an acknowledgment that delivery succeeded. That acknowledgment does not prove that the customer completed downstream work. A receiver might return success, then fail while updating a database or doing another task.
Explain what happens after the receiver acknowledges the request with a successful response: the provider may stop sending the event, even if the receiver later fails to process it. Recommend that receivers store the event or put it in a durable queue before acknowledging it. They can then handle longer-running work separately. Shopify’s order webhook guidance recommends responding with a successful status promptly and moving long-running work out of the request path.
Separate automatic retries from manual redelivery
With automatic retries, the provider tries to send a failed notification again without waiting for a customer to ask. With manual redelivery, a customer asks the provider to try again. Document these as separate capabilities. A provider that retries automatically does not necessarily offer manual replay, and a manual redelivery feature does not establish that the provider will retry on its own.
Describe the retry schedule and its limits: when the first retry happens, how the delay changes, how many times the provider tries, and when it stops. If the provider disables or removes a webhook subscription after repeated failures, state what triggers that action and what the customer must do to resume delivery.
When customers can request redelivery through an API, document the HTTP method and path, the identifiers and permissions required, and the response the endpoint returns. Explain what a successful response confirms: that the provider accepted the request, started an attempt, or delivered the event to its destination. Also explain relevant errors, rate limits, and whether repeated requests can cause duplicate processing. GitHub, for example, documents separate requests for listing repository webhook deliveries and asking for another attempt, with credentials required for the operation in its redelivery API example.
If customers can only redeliver through a dashboard, name that limitation and where to find the control. If the provider offers no redelivery method, say so and document any alternative recovery route. Do not imply that customers can replay an event through an undocumented endpoint.
Because providers handle failures differently, describe each product's behavior precisely. Shopify documents automatic retries; GitHub says it does not automatically redeliver failed deliveries and instead documents customer-driven recovery in its failed-delivery instructions. Stripe Support describes retries over several days and possible endpoint disabling after persistent failures, but does not give an exact retry count or schedule in the cited support guidance. Do not generalize one provider’s policy to other webhook products or configurations.
Help customers find the failed attempt
Customers need to find the failed delivery and see what happened during the attempt. A delivery lookup should expose stable identifiers, the event type, the destination, attempt times, and the response status or connection error. If the provider stores the payload, explain how customers can retrieve it. Document pagination, which splits results across pages, and any time-range restrictions so customers know how to search older records.
Keep delivery records distinct from event records. A delivery record describes one attempt to send a notification and its result. An event record describes the underlying occurrence. An API that retrieves an event does not necessarily show whether the provider tried to deliver it, what response the receiver returned, or whether another attempt is available.
State where customers can search and which webhook categories the lookup covers. Shopify documents delivery details in its Dev Dashboard, including response code, topic, shop, and time; those logs cover seven days and can lag by several minutes. Its cited troubleshooting documentation describes dashboard logs, so the reference should not present them as a general API for querying failed attempts. GitHub also documents categories for which its delivery-data APIs do not provide records. These boundaries matter when customers investigate missing notifications.
State each recovery window and limit
One retention period can obscure several different time limits. Document the automatic retry period, the delivery-history window, the manual-redelivery window, and the period when customers can retrieve the event itself. If customers can reconcile missed changes through resource APIs, explain the applicable history or query limits for that method too.
The provider examples show why these windows should not be combined:
| Provider | Documented behavior | What the limit applies to |
|---|---|---|
| Shopify | Up to eight retries over four hours; repeated failures can lead to subscription removal. | Automatic attempts. Dev Dashboard delivery logs cover seven days and may lag by several minutes. |
| GitHub | Failed deliveries are not automatically redelivered. Customers can request redelivery for deliveries from the past three days. | Manual redelivery eligibility. |
| Stripe | Support describes retries over several days and possible endpoint disabling after persistent failures. | Automatic attempts; the cited guidance gives no exact schedule or count. The Events API provides 30 days of event access. |
Shopify’s limits appear in its troubleshooting documentation; GitHub documents its three-day redelivery window in its redelivery instructions; and Stripe’s Events API reference describes event access. Stripe’s 30-day event window does not establish a 30-day delivery-history or redelivery window. Name the object each limit applies to, and do not imply that event retrieval guarantees access to the original delivery attempt.
Also document operational restrictions that affect recovery. State which roles are required and which webhook categories the provider does not support. Describe any attempt caps and pagination rules, along with applicable rate limits. If a limit varies by product or configuration, identify the scope. If the provider does not offer a particular capability, state that directly.
Explain recovery after redelivery ends
When the provider can no longer send a delivery again, customers need a clear next step. Reconciliation means querying an API for resource data to check or repair the customer’s current state. For example, a customer that missed a notification could query the relevant resources and compare their current state with its own records. Shopify recommends periodic reconciliation because webhook delivery is not guaranteed in its webhook overview.
Describe what reconciliation can recover. An API that returns current resource state may let customers restore that state without revealing every intermediate change. Do not promise that reconciliation reconstructs every missed event unless the provider retains and exposes a complete event history.
Retries and manual redelivery can cause a receiver to process the same notification more than once. A receiver should recognize when it has received the same notification again and avoid applying the change twice. Explain which identifier represents one delivery attempt and which identifier links deliveries to the same underlying event, if the provider exposes both. Shopify’s delivery structure documentation distinguishes a delivery identifier from an event identifier shared across deliveries associated with the same merchant action.
What I'm buildingDelegate tasks. Get software.
Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.
Take a look at vroni.com