API documentation · Research synthesis
What does a successful webhook delivery actually prove?
Compare webhook acknowledgment and recovery policies across Stripe, GitHub, Shopify, Slack and AWS, with a practical checklist for documenting lost and repeated work.
A successful delivery records an acknowledgment, not necessarily a completed business operation. Useful webhook documentation must explain where work becomes durable, which system retries each failure, and how operators recover anything left behind. This review separates those promises using eight official sources and a proposed acceptance exercise.
Key findings
Acknowledgment deadlines and retry policies belong to specific providers and delivery modes. A generic promise that failed webhooks will retry is unsafe.
Delivery success, durable acceptance and completed processing need separate definitions and evidence.
Replay can restore missed work and also repeat completed work. Recovery instructions need duplicate handling and a defined scope.
A dead-letter queue helps only at the boundary it covers. Its existence does not establish that later business processing succeeded.
How we researched this
We reviewed eight official documentation pages from Stripe, GitHub, Shopify, Slack and Amazon Web Services on November 15, 2026. We selected them to examine contrasting acknowledgment and recovery contracts, not to rank providers or estimate industry prevalence. Numeric values below describe documented policies, defaults or configuration options, not measured performance. We independently opened the original sources after research discovery. The state model, incident examples and acceptance exercise are our synthesis and recommendations; we did not run a webhook benchmark.
Start by defining what succeeded
Imagine an account-creation event that should provision a workspace. The sender records a successful webhook delivery. The workspace never appears. Both observations can be true: the endpoint acknowledged the request, but the application failed later.
For documentation, the useful question is where responsibility changed hands. Did the receiver commit a durable job, or merely start a task in the request process? Does the application have evidence of the intended result? The following model is our proposed way to make those questions answerable.
| State | What the operator can establish | Evidence the integration should retain |
|---|---|---|
| Received | A request reached the endpoint | Attempt identifier, arrival time and verification result |
| Durably accepted | Work was committed to a recoverable store | Queue receipt or committed inbox record tied to the event |
| Processed | The intended operation completed under its defined rules | Operation result and stable business identifier |
| Reconciled | Expected source state was compared with local state | Checkpoint, discrepancy report and recovery outcome |
These are design definitions, not universal provider statuses. An implementation may combine some steps in one transaction. Another may distribute them across services. Its docs should say which evidence supports each claim.
For example, a dashboard label of “delivered” is ambiguous unless its definition says whether it records an HTTP response or a completed operation. A receipt is useful evidence, but it should not become a stronger promise as it passes through a support ticket.
Write the definition next to the status, not only in an architecture document. A developer integrating the product should know what a green delivery row means before an incident forces them to investigate it. The same distinction belongs in examples: a response followed by background work needs an explanation of who owns that work after the response.
What the provider policies actually say
The comparison below concerns published delivery behavior. It is not a reliability ranking. A longer retry window can help during an outage, but does not prove better application outcomes. Read each row within its stated delivery mode.
| Provider and scope | Acknowledgment or delivery boundary | Documented recovery behavior |
|---|---|---|
| Stripe webhooks | Return a successful response promptly; no numeric deadline asserted here | Live-mode automatic retries last up to three days with exponential backoff. Sandbox behavior differs. Stripe |
| GitHub webhooks | Return a 2xx response within 10 seconds | Failed deliveries are not automatically redelivered. Recovery requires manual redelivery or a mechanism you arrange. Handling, recovery |
| Shopify HTTPS webhooks | One second to establish a connection; five seconds for the entire request | Eight retries over four hours. After eight consecutive failures, deletion applies to subscriptions configured through the Admin API. Shopify |
| Slack Events API over HTTP | Acknowledge within three seconds | Three retries by default, roughly immediately, after one minute and after five minutes. Optional Delayed Events adds hourly retries for 24 hours afterward. Slack |
| EventBridge rule target delivery | Delivery to the configured target, rather than proof of its business outcome | By default, retriable failures are retried for up to 24 hours and up to 185 times; policy is configurable. AWS |
A developer cannot safely copy one row into another integration. The numbers refer to different clocks: establishing a connection, returning an HTTP response, or retrying a target delivery. They also describe limits and schedules, not guaranteed recovery times.
The practical documentation task is to capture the selected configuration alongside the provider default. If the integration enables an optional recovery feature, say so. If it relies on the default, name that assumption. A link to a provider page is useful, but leaves the reader guessing about your deployment unless you state what is actually enabled.
Avoid an undated sentence such as “we retry failed events.” Identify the sender, delivery mode, failure classes and stopping condition. Record when the policy was checked. When a setting changes, the recovery instructions and operator expectations should change with it.
What happens if the process stops after acknowledgment?
Consider three hypothetical sequences. These are reasoning examples, not observed incidents or experimental results.
Sequence one: work exists only in memory. The endpoint verifies a request, adds a task to a process-local list, returns success and then crashes. The intended task has no durable record. If the sender treats that acknowledgment as successful delivery, the receiver cannot rely on a failure retry to reconstruct its lost work.
Sequence two: a durable job exists. The endpoint commits an inbox record or obtains a durable queue receipt before acknowledging. A worker later crashes. The job can still be discoverable, but completion now depends on the consumer's lease, retry and recovery behavior. “We use a queue” is incomplete documentation unless those responsibilities are defined.
Sequence three: the operation succeeds but the acknowledgment is lost. The receiver performs the business operation. The sender does not receive the response and may try again according to its policy. The receiver must distinguish a repeated delivery from a new operation before repeating an expensive or irreversible effect.
Our recommendation is to document the acceptance boundary as an explicit sequence. Verify the request, establish durable ownership of valid work, then acknowledge according to the provider contract. Keep the response path short by moving longer processing behind that boundary. This is a design recommendation, not a claim that every queue or database automatically provides the required guarantees.
There are tradeoffs. Durable acceptance can itself fail or take too long. A receiver that cannot store the work must follow the provider's failure contract and expose the incident, rather than silently reporting acceptance. For a sender without automatic redelivery, an unsuccessful response still needs a separate recovery path; an error code alone does not repair the lost opportunity.
The documentation should let an operator answer: what record survives if this process stops at this line? That question is more useful than an example that returns success quickly without explaining where the work lives afterward.
Which identity prevents the wrong work from repeating?
Stripe documents both duplicate delivery and a lack of guaranteed event ordering. Shopify distinguishes a webhook ID used to deduplicate an individual delivery from an event ID that can relate notifications across subscriptions. These are reasons to define identity explicitly rather than treating every identifier as interchangeable. Stripe, Shopify
Our recommended contract separates three concepts:
- Delivery identity: the notification being received or retried.
- Source identity: the underlying event or resource change, where the provider supplies one.
- Business operation identity: the local effect that must not happen twice, such as creating a particular entitlement.
A delivery deduplication check does not, by itself, define whether two different events should produce the same business effect. Conversely, using a resource ID as a permanent suppression key could discard legitimate later changes to that resource. The docs should explain the chosen key's scope and lifetime, including account or tenant boundaries.
The record's state matters as much as its key. Suppose a receiver writes “seen” and then crashes before committing the effect. If the next attempt treats “seen” as “finished,” the duplicate check can hide unfinished work. If two workers both check for absence before either writes, they may both proceed. These are hypothetical failure cases that the implementation and its example should address together.
Describe the claim or lock operation, what counts as completion, and how abandoned work becomes eligible again. Do not present a separate lookup followed by an insert as an atomic guarantee without supporting implementation behavior.
Ordering needs its own policy. A late notification might require fetching current resource state, applying a version check, or rejecting an obsolete transition. Which approach is appropriate depends on the operation. A current-state refresh can be useful for a status display, but it cannot substitute for every historical action. Explain the intended semantics instead of promising that one universal handler solves both problems.
Where does retry responsibility move next?
EventBridge can send undeliverable rule-target events to a configured dead-letter queue. Its documentation also identifies errors, including missing permissions or a nonexistent target, that can go directly there without retries. That queue covers the delivery failure it records; it is not proof that downstream work completed. AWS dead-letter queues
AWS Lambda asynchronous invocation illustrates a separate processing boundary. For function errors, its default behavior includes two additional attempts, with waits of one minute and then two minutes. Its documentation also warns that duplicate events are possible even without a function error. These statements concern asynchronous invocation, not a generic synchronous HTTP handler. Lambda
The lesson is to draw a recovery map for the actual integration. An event can pass one service's delivery boundary and then fail within another service's execution boundary. Each needs an owner, evidence and a stopping rule.
| Failure location | Question the docs must answer | Recommended evidence |
|---|---|---|
| Before receiver acceptance | Does the sender retry, and can a human request redelivery? | Sender attempt record and response outcome |
| After durable acceptance | Which consumer retries unfinished work? | Queue or inbox state, attempt history and lease owner |
| During a business operation | Is the effect safe to repeat or resume? | Operation identity and committed result |
| After recovery is exhausted | Who investigates and what can they replay? | Retained failed record, reason and recovery ticket |
This table is a proposed responsibility map, not a description of one provider's architecture. Populate it with real names and tools. “The platform handles retries” is insufficient if nobody knows which platform, which failures, or when it stops.
A failed-record store also needs an operator procedure. Explain how to inspect a record without executing it, distinguish a permanent configuration problem from a temporary outage, and select a bounded replay. Record whether the replay succeeded at delivery or at business processing. Otherwise, the recovery dashboard can reproduce the original ambiguity in a different location.
How should recovery work after the outage?
Stripe allows manual resends within different windows: up to 15 days after event creation through its Dashboard and up to 30 days after event creation through the CLI. A manual resend does not cancel the automatic retry behavior. Shopify recommends a reconciliation job for missed updates. These are different recovery tools, not interchangeable guarantees of historical completeness. Stripe, Shopify
Our proposed recovery procedure starts with a question: are you repairing current state or reproducing historical effects? Updating a local customer's present subscription status is different from sending every notification that should have been sent during an outage. A present-day API response might help with the first task without reconstructing the second.
For a replay, define a bounded set of records and the reason they qualify. Include the affected account, time interval, event identity and known processing state where available. Explain how a retry already in flight interacts with the replay. If operators must stop a consumer first, document that requirement and the consequence for new work.
For reconciliation, specify the authoritative source, traversal method and checkpoint behavior. Record what the comparison can establish. If the source provides only current state, say that it cannot independently prove every earlier transition was processed. If historical records expire, name the window the recovery procedure actually supports.
A useful runbook ends with verification, not a button press:
- Identify the affected scope and preserve the failure evidence.
- Correct the underlying cause before replaying its consequences.
- Preview the candidate records and exclude effects already confirmed complete.
- Replay or reconcile a bounded batch using the documented duplicate safeguards.
- Compare the resulting business state with the intended outcome.
- Retain unresolved exceptions and record who owns them next.
These steps are recommendations, not a claim that the providers supply a single workflow. The integration team must implement the necessary visibility. A support agent should be able to explain what was repaired and what remains uncertain without interpreting a successful HTTP response as proof of everything downstream.
A proposed acceptance exercise for the docs and implementation
A delivery contract becomes more useful when its promises can be challenged. The matrix below is a proposed exercise for a controlled test environment. We have not executed these tests, and the rows are not benchmark results. Use synthetic events and disposable resources; never induce failures in customer workflows to validate a documentation example.
| Exercise | Observe | Acceptance criterion to define |
|---|---|---|
| Lose the acknowledgment after the effect commits | Whether redelivery repeats the effect | One intended effect, with the repeated attempt traceable |
| Fail durable storage before acknowledgment | The response and recovery path | No false acceptance; an explicit way to recover |
| Stop the worker after durable acceptance | Job state after restart | Unfinished work remains discoverable and recoverable |
| Deliver the same event concurrently | Competing claims and effects | Duplicate handling holds under overlap, not just sequential calls |
| Deliver relevant events out of order | Resulting resource state | The documented stale-event policy is followed |
| Exhaust the configured retries | Retained evidence and escalation | A named owner can find and handle the failed work |
| Replay while an automatic retry is pending | Combined processing history | Recovery does not bypass the duplicate safeguards |
| Submit an invalid signature | Authentication outcome and side effects | Rejected requests produce no business effect |
Specify the observation point before running each exercise. A sender's success log cannot establish a database effect that only the receiver can observe. Likewise, a worker log entry saying “started” cannot establish that its transaction committed.
Record the exact configuration, event fixture, failure injection point and expected result. After the exercise, retain evidence for both the delivery outcome and the business outcome. If a test passes only after a manual intervention, include that intervention in the runbook rather than describing the process as automatic.
There are important boundaries to this approach. A local simulation can validate your own crash handling while missing provider-specific redelivery behavior. A real-provider sandbox can exercise the integration while using different retry timing from live service. Neither justifies a blanket reliability claim. Label what was actually tested and what was checked only against documentation.
For documentation teams, a failed exercise is also an editorial finding. It may reveal an unsupported promise, a missing recovery instruction, or a sample that teaches an unsafe sequence. Resolve the implementation or narrow the promise before publishing the example.
Make the status page and the recovery page agree
Our final recommendation is to design the operator view and the public explanation together. A useful integration status should distinguish accepted work, pending work, completed operations and unresolved failures. Where those distinctions are not observable, the docs should say so.
Keep metric denominators explicit. Delivery attempts count retries as well as initial attempts. Unique accepted events count something different. Completed business operations may have a different relationship again when several notifications refer to one intended effect. Comparing those totals without a defined mapping can turn an ordinary retry into an apparent increase in throughput.
Prefer operational questions over one unlabeled success percentage:
- How old is the oldest accepted item without a completed outcome?
- Which failures have exhausted their automated recovery path?
- Which completed operations were protected from a repeated effect?
- When did the last reconciliation finish, and what did it leave unresolved?
- Can support trace a reported problem from source identity to local result?
These are proposed measurements, not industry benchmarks or required features of the providers reviewed. Their value depends on retaining appropriate evidence with suitable access controls and retention limits. Avoid logging secrets or unnecessary payload data just to make a trace easy to follow.
A good webhook reference still needs payloads, event names and signature instructions. The missing layer this report addresses is the delivery contract: what success means, who owns unfinished work, when recovery stops and how the outcome is verified. Make that layer explicit and a green delivery indicator becomes useful evidence instead of an invitation to guess.
Limitations
This is a purposeful review of eight official pages, not a representative survey, provider ranking or measured reliability study. Policies were checked on November 15, 2026 and may change. Optional settings, delivery modes and live versus sandbox behavior affect the contract. We did not measure latency, execute failure injections, verify any customer implementation or establish exactly-once processing. The proposed state model, exercises and runbook require adaptation to the actual data store, queue and business operation. Current-state reconciliation does not necessarily reconstruct historical events.
Sources
- Receive Stripe events in your webhook endpointStripe · Accessed 2026-11-15
- Handling webhook deliveriesGitHub · Accessed 2026-11-15
- Handling failed webhook deliveriesGitHub · Accessed 2026-11-15
- Verify webhook deliveriesShopify · Accessed 2026-11-15
- The Events APISlack · Accessed 2026-11-15
- How EventBridge retries delivering eventsAmazon Web Services · Accessed 2026-11-15
- Using dead-letter queues to process undelivered events in EventBridgeAmazon Web Services · Accessed 2026-11-15
- How Lambda handles errors and retries with asynchronous invocationAmazon Web Services · Accessed 2026-11-15