A successful happy-path delivery says little about retry behavior. Define the intended business effect first, then give each failure fixture an expected effect and an observed result. This page uses a deliberately synthetic event identity and resource version; do not assume your provider supplies the same contract.
A useful six-case set
- Identical duplicate: deliver one event twice. In guarded mode, inspect one applied result and one duplicate.
- Failure before write: use failOnce:true, then deliver again. The first attempt fails; the next can apply.
- Older update arrives later: version 3 followed by version 2 for one resource. Guarded mode keeps version 3.
- Equal version, conflicting value: use different event IDs and the same resource/version with different values. Review the version_conflict.
- Concurrent duplicate: enable concurrent delivery with identical IDs. The in-flight promise shares completion within this single process.
- Reused ID, changed content: keep the ID but change its value. Guarded mode reports a collision instead of treating it as harmless replay.
Run these fixtures in HookReplay and compare naive mode where relevant. Its example sequence deliberately contains a failure, a retry, a stale update and a duplicate. Record the actual write count and final resource state.
Draw the tested boundary accurately
The simulator has no HTTP receiver, signing secret, durable database or distributed queue. Its Map disappears on restart. Passing concurrent fixtures in one JavaScript process does not validate multiple workers or a crash after an external side effect. A production design needs provider-specific sender verification and an appropriate atomic persistence and recovery boundary.
Event identity and sender authenticity are different checks. Consult the sender’s contract; for one provider, see Stripe’s webhook documentation. Never paste signing secrets into a public demo.
Include payload observations
ContractLens compares observed JSON types. A number becoming a string is a sample observation. An empty array cannot establish which item fields still exist, and unchanged sample types cannot prove complete compatibility. Keep the real contract and consumer integration tests alongside the sample report.
WebhookLab provides a written lesson and quiz preview. Its complete download includes six lessons and runnable offline exercise pages. A quiz record is a learning note, not a professional certificate.