BlogIntegration events
Failing webhooks: retrying without duplicate work or lost events
A provider receiving “200” does not establish that operations were updated. Separate receipt, processing and verification of the result.
Test worksheet: Webhooks: retry and duplicate-work acceptance
A provider receiving “200” does not establish that operations were updated. Separate receipt, processing and verification of the result. Record inputs, expected outcome, evidence, owner and observed result.
Define what each confirmation means
A webhook is a notice one system sends another when something happens. For a carrier it may report a completed delivery; for services, available evidence files. Technical receipt and business acceptance are different states. Decide where each can be queried and who resolves an event left pending.
Stripe documents signature validation and a quick successful response before complex logic. Shopify publishes retry conditions and failed-delivery monitoring. These are specific provider contracts, rather than universal rules for all connections. Confirm your provider's timing, authentication and identifiers before designing receipt.
Fictional example: delivery notice EV-72
The routing system sends EV-72 for delivery E-017. The receiver checks authenticity, durably stores the event and acknowledges receipt. Updating E-017 remains pending because a document is missing. The provider repeats EV-72 after not receiving the first response. This is a synthetic operational-event example, rather than a charge or an already implemented integration.
The expected result is one received event with two delivery attempts and no second operation caused by the retry. Once the document is available, an authorized owner or process resumes work and marks E-017 updated. History separates receipt from application. If the event was never saved, acknowledging success would have hidden a loss; that rehearsal case must fail.
| State | What it demonstrates | What remains |
|---|---|---|
| Received | Authenticated, retained notice | Apply or decide the work |
| Pending | Locatable event with a reason | Resolve dependency and retry |
| Applied | Verifiable business result | Reconciliation where relevant |
| Rejected | Not applied for an explicit reason | Authorized correction or closure |
Rehearse failure at every boundary
Use a test environment and authorized origin. Test before and after storing the event, before and after applying the change, and after losing the response. An event identifier recognizes its redelivery, but may not distinguish two different notices about one operation. Agree the operation key that must not execute twice as well.
| Case | Expected result | Evidence |
|---|---|---|
| Authentic complete EV-72 | Durable receipt and identifiable task | Event and related task |
| EV-72 arrives twice | One business task, two visible attempts | Event key and attempts |
| Response lost after application | Retry finds the existing result | Operation reference |
| E-017 document missing | Pending with reason; not reported applied | State and dependency |
| Earlier notice arrives late | Does not overwrite newer state without a rule | Versions and decision |
| Invalid signature or authentication | Rejection without changing delivery | Outcome and bounded record |
Retries need limits and an exit path
Define internal attempt limits, retryable errors and the owner for exhausted attempts. Do not retry a nonexistent reference or denied permission forever without fixing its cause. A pending queue needs visible age and responsibility; “it will retry” does not explain when the operation can continue.
Include reconciliation: compare source events or states with applied destination results. It can detect notices that never arrived or fell outside the queue. Frequency and scope depend on provider API and access. Retaining notices does not necessarily recover the complete history, and manual replay does not bypass duplication rules.
Accept an integration through its business outcome
Test lookup and repair by reference as well as technical delivery. Connecting an ERP without replacing it explains data authority; synchronization rules help with concurrent changes, and a change audit log explains what was applied.
The downloadable worksheet contains ten cases to adapt to the actual provider. Bring an anonymized notice, its identifiers and a known failure to a free consultation on process automation. We can review confirmation boundaries and a useful test of recovery without duplicate work.
Frequently asked questions
It means what the receiver contract defines. It may acknowledge receipt only. The buyer needs a separate business-result state and a way to query pending or rejected work. Do not infer correct application from the HTTP response alone.
Recognize redelivery, but check the original task's state. Pending work may need a controlled retry. Ignoring the notice without retaining or recovering the task can lose the expected result.
Define a rule using version, sequence or an authorized source-state lookup. Arrival time should not automatically become business truth. The provider determines available options; test an earlier notice arriving later.
It does not replace payment reconciliation. Distinguishing a repeated notice from an actual second charge requires reviewing transactions and orders. This rehearsal focuses on delivery and application of operational events in a connection.
Sources
Last updated: