API Reliability
Webhook Replay Debugging Guide
Replay webhooks safely with captured metadata, idempotent handlers, signature-aware fixtures and observable delivery outcomes. This reference is written for developers who need practical validation behavior, reviewable rules and safe examples rather than copied snippets with no explanation.
Recommended workflow
| Step | Why it matters |
|---|---|
| Capture a safe fixture | Keep event type, delivery ID, timestamp and redacted body without retaining secrets. |
| Choose the verification mode | Use a test secret and regenerated signature when validating the full HTTP handler. |
| Replay in isolation | Point at staging or a local endpoint with outbound side effects disabled. |
| Verify deduplication | The same delivery ID should not create a second durable action. |
Starter snippet
store redacted fixture -> preserve event id -> replay in staging -> verify one durable side effectReview checks
- Preserve the raw body when signature verification depends on bytes.
- Record replay origin separately from live delivery.
- Expire stored fixtures according to data policy.
- Test retry ordering as well as duplicates.
Common mistakes
- Replaying a production event against production.
- Changing JSON whitespace before checking the original signature.
- Using timestamps that the verifier correctly considers expired.
Validation should help users correct input while protecting systems from bad data. Keep syntax checks, product policy, security review and deliverability checks separate.
Related Formalint references
Continue with Webhook Debugging Guide, Webhook Signature Verification Guide, Api Idempotency Retry Guide.