Separate receipt from completed processing
Guarantees depend on the provider. Stripe documents possible duplicates and no guaranteed ordering. A successful HTTP response should correspond to durable receipt or the intended processing, not just a request arriving in memory.
| Situation | Expected behavior | Useful evidence |
|---|---|---|
| Same event received twice | Prevent a repeated business effect. | Processed ID and persistent outcome. |
| Older event arrives later | Do not blindly overwrite newer state. | Authoritative state and transition rule. |
| Heavy processing | Durable receipt followed by deferred work. | Queue state and worker outcome. |
| Missing delivery | Reconcile and recover under provider rules. | Identified gap and verified correction. |
Build verifiable reception
- Check HTTPS, signatures and replay protection under the provider’s protocol. Stripe signature verification uses the raw body; transforming JSON first can invalidate verification.
- Durably record the event or its processing before the appropriate acknowledgement. Distinguish delivery ID, event ID and the business action’s idempotency key.
- Test duplicates, out-of-order events, worker interruption and restart. Retrieve the authoritative object state when an old event cannot support a safe decision.
Organize recovery and reconciliation
Document attempts, timing, unprocessed events and reconciliation with the provider. A quick acknowledgement can hide later processing failure. Monitor the final business action too and keep secrets and personal data out of unnecessary logs.
Primary references
Handle repeated webhooks safely
A notification may be repeated after a timeout or lost response. Reliability depends on origin verification, an event identifier and processing that separates a new message from a duplicate.
- Verify each request using the provider’s mechanism.
- Test retries, duplicates and changed arrival order.
- Acknowledge consistently after processing or durable queuing.
Primary reference: IETF RFC 9457 — Problem Details for HTTP APIs. Related method: read the practical guide.