Webhook Replay Lab
Webhook Replay and Idempotency Checklist
Replay duplicate deliveries against a sandbox and count durable side effects. Two accepted deliveries should still create one effect when they represent the same scoped event.
Worked example
| Synthetic delivery | Event | Expected durable effects |
|---|---|---|
| Initial delivery | event-001 | 1 |
| Retry after lost acknowledgement | event-001 | 1 |
| New event | event-002 | 2 |
The retry leaves the total at one. The new event increments it to two. Compare the durable ledger with these counts after restarting the handler.
How to run the check
- Record the provider account, event ID, attempt ID and expected effect.
- Deliver the event, simulate a lost acknowledgement, then resend it after a restart.
- Compare the downstream ledger with the fixture. Stop if an effect is missing or duplicated.
Use synthetic payloads and sandbox destinations. The correct key scope and retention period depend on the provider and your recovery policy.
Why count effects instead of successful responses?
Multiple delivery attempts can be accepted without repeating a database write, an email or another external effect.
Reference: GitHub webhook best practices