Resources · 54
Webhooks: handle repeats, delays and recovery
Turn a received notification into a unique, traceable business effect recoverable after failure.
· 3 min
What this guide helps achieve
- Authenticate notifications
- Separate receipt from processing
- Prevent duplicate effects
- Recover blocked events
Quick check
- Which bytes are signed?
- When is receipt durable?
- Can two workers act together?
- Does the provider guarantee order?
- How is a lost event found?
Step-by-step method
- 01
Read the provider contract
Record types, version, account context, signatures, timing and retry rules. Stripe states that delivery ordering is not guaranteed and duplicates can occur; do not apply a Stripe-specific delay to every API.
Deliverable: dated provider contract.
- 02
Validate before effects
Check signatures with the library and raw body required by the provider. Limit accepted sizes and types. Test invalid signatures and unexpected account context in an authorised environment without logging secrets.
Deliverable: denials with no effects.
- 03
Persist before acknowledging
Separate durable receipt from slow processing. If the queue cannot accept the event, do not report it as retained. Success indicates receipt under your contract, not necessarily completion of the business action.
Deliverable: received, processing, completed and blocked states.
- 04
Enforce idempotency
Define event keys and business-effect identity. Test concurrent repeats rather than only sequential delivery. A preliminary check without atomic constraints or locking can allow two workers to create the same effect.
Deliverable: evidence of effect uniqueness.
- 05
Handle delay and disorder
Do not assume an old notification describes current state. Consult the source when the contract permits and apply validated business transitions. Retain events that cannot yet be interpreted.
Deliverable: transitions and reversed-order tests.
- 06
Reconcile and replay
Prepare an error queue with owner, cause, attempts and closure. Keep duplicate protection during replay. Periodically compare provider and application: successful recovery does not prove no event was missed.
Deliverable: recovery procedure and discrepancy report.
Reusable worksheet
Complete with your authorised observations. These fields are a working template, not observed results.
| Field | Information to record |
|---|---|
| Event | Provider, account, identifier and version |
| Receipt | Validated signature and durable timestamp |
| Effect | Business key, state and uniqueness evidence |
| Recovery | Cause, attempt, owner and closure |
Worked example
Illustrative situation
Fictional example: two workers receive the same confirmation notification during recovery.
Decision and expected evidence
A unique business-effect constraint and transactional state permit one fulfilment while both deliveries remain traceable.
Distinguish the mechanisms
| Mechanism | Purpose | Check or limitation |
|---|---|---|
| Signature | Validate origin under the contract | Does not make effects unique |
| Deduplication | Recognise repeat notifications | Also check concurrency and business effects |
| Reconciliation | Find omissions and differences | Name the source and period |
Management indicators
| Indicator | What it measures | First action |
|---|---|---|
| Queue age | Delay of unfinished events | Inspect the oldest |
| Duplicate effects | Business actions repeated in error | Correct atomicity |
| Source / application gaps | Absent or divergent states | Reconcile with closure evidence |
Common pitfalls
- Parsing before signed-body verification
- Acknowledging before durable receipt
- Assuming ordered delivery
- Testing duplicates only sequentially
Frequently asked questions
Does HTTP success mean processing is complete?
It depends on the contract. With asynchronous processing, it should mean durable receipt while business state is tracked separately.
Can exactly-once delivery be assumed?
Design for repeats and failures under the real contract, with unique effects and reconciliation.
Should the entire body be retained?
Only when necessary with suitable access and retention. Minimal traces should support diagnosis and recovery without keeping secrets.
Official references
References consulted on 2 October 2026. The method and worksheet propose checks to adapt to your context; they do not constitute certification.
Continue exploring
Related analysis
