A webhook reports an external event; delivery does not prove that your business operation completed. Design validation, deduplication and recovery as separate responsibilities.
Separate receipt from processing
For a fictional subscription product, a payment notification may repeat or arrive out of order. Verify the provider's signature, durably record the event and then manage processing. Do not label the business operation complete until its intended effect is confirmed.
| Condition | Expected behaviour |
|---|---|
| Duplicate event | One business effect |
| Interrupted worker | Identifiable recovery path |
| Old event | No inconsistent regression of state |
| Invalid signature | Rejection with appropriate logging |
Provide reconciliation
Retain the external identifier, event type and processing status without copying unnecessary sensitive payloads into logs. When local history is incomplete, compare with the provider's authoritative state. Exact retry and ordering behaviour varies by provider; use its current documentation rather than assuming all webhook systems behave alike.
Can the endpoint immediately return success?
Only when receipt has actually been accepted under your processing contract. A successful response before durable storage can lose an event during failure. Conversely, a long synchronous operation may time out and trigger repeated delivery. Exercise duplicate delivery, interruption between steps and manual replay in a test environment. Confirm the final business state, not only the endpoint's response code.
Provider time is not processing time
Retain both the event's reported time and the time your system processed it. A delayed event from a provider in another region should not look like a new business action simply because it arrived today. Use identifiers and authoritative state to reconcile it.
Sources and further reading
From this guide to your project
Development ↗
A SaaS is a system: data, users, permissions, billing and operations. Its architecture should support the business model.
Tell us about your ideaExamples are educational and do not describe client results. Content prepared with AI assistance; see our editorial policy. Our method ↗