| name | webhook-handler-patterns |
| description | Best practices for webhook handlers. Use when implementing the handler sequence (verify first, parse second, handle idempotently), idempotency, error handling, retry logic, or framework-specific issues with Express, Next.js, or FastAPI.
|
| license | MIT |
| metadata | {"author":"hookdeck","version":"0.1.0","repository":"https://github.com/hookdeck/webhook-skills"} |
Webhook Handler Patterns
When to Use This Skill
- Following the correct webhook handler order (verify → parse → handle idempotently)
- Implementing idempotent webhook handlers
- Handling errors and configuring retry behavior
- Understanding framework-specific gotchas (raw body, middleware order)
- Building production-ready webhook infrastructure
Resources
Handler Sequence
Best Practices
Framework Guides
Quick Reference
Handler Sequence
- Verify signature first — Use raw body; reject invalid requests with 4xx.
- Parse payload second — After verification, parse or construct the event.
- Handle idempotently third — Check event ID, then process; return 2xx for duplicates.
See references/handler-sequence.md for details and links to provider verification and idempotency patterns.
Response Codes
| Code | Meaning | Provider Behavior |
|---|
2xx | Success | No retry |
4xx | Client error | Usually no retry (except 429) |
5xx | Server error | Retry with backoff |
429 | Rate limited | Retry after delay |
Idempotency Checklist
- Extract unique event ID from payload
- Check if event was already processed
- Process event within transaction
- Store event ID after successful processing
- Return success for duplicate events
Related Skills
