Designing payment webhooks for retries
A durable approach to signature validation, idempotency, asynchronous work, and controlled replay.
Duplicate delivery no longer meant duplicate business effects
The risk
Providers retry valid events when acknowledgements are delayed or lost. Processing every delivery as new work can create duplicate fulfillment, emails, or financial changes.
The design
Receipt, validation, and business processing became distinct responsibilities.
- Validate signatures against the raw request body
- Persist provider event IDs under a unique constraint
- Acknowledge quickly and queue durable processing
- Make downstream side effects safe to retry
- Keep an audit trail and controlled replay path
The trade-off
The design adds durable state and operational tooling, but that cost is justified when duplicate side effects can harm customers or require manual financial correction.