ReferenceIntermediate4-6 min reference
Webhook Testing
A webhook is an outbound HTTP callback: the provider POSTs an event to your URL when something happens. They fail in ways normal request/response APIs don't — duplicates, retries, out-of-order delivery, replay attacks. This sheet is the checklist of properties to test; use the webhook payload tester utility (linked below) to capture and inspect payloads.
Properties to test
| Property | Test | Expected |
|---|---|---|
| Delivery | Trigger the source event | Endpoint receives a POST |
| Payload | Inspect body + headers | Matches documented schema |
| Signature | Tamper / wrong secret | Rejected; valid signature accepted |
| Retries | Return 500/timeout | Provider retries with backoff |
| Idempotency | Same event delivered twice | Handler processes it once |
| Ordering | Events arrive out of order | Handler tolerates / reorders |
| Duplicates | Replay an old event | De-duplicated by event id |
| Ack | Slow handler | Respond 2xx fast, process async |
| Replay attack | Re-send a captured request | Rejected via timestamp/nonce |
Status code contract
- Respond
2xxquickly to acknowledge receipt — do the heavy work asynchronously. - A non-
2xx(or timeout) tells the provider to retry, so a slow handler causes duplicate deliveries. - That's exactly why idempotency keys / event ids matter.
Common mistakes
- Assuming exactly-once delivery — webhooks are at-least-once; design for duplicates.
- Doing slow work before returning
2xx, triggering retries and duplicate processing. - Skipping signature verification, leaving the endpoint spoofable.
- No replay protection (timestamp/nonce), so old captured events can be re-sent.
- Testing only the happy delivery, never retries or out-of-order arrival.
// Related resources