Agent Skill · Hookdeck
webhook-handler-patterns
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.
Skill body
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
- references/handler-sequence.md - Verify first, parse second, handle idempotently third
Best Practices
- references/idempotency.md - Prevent duplicate processing
- references/error-handling.md - Return codes, logging, dead letter queues
- references/retry-logic.md - Provider retry schedules, backoff patterns
Framework Guides
- references/frameworks/express.md - Express.js patterns and gotchas
- references/frameworks/nextjs.md - Next.js App Router patterns
- references/frameworks/fastapi.md - FastAPI/Python patterns
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
- stripe-webhooks - Stripe payment webhook handling
- shopify-webhooks - Shopify e-commerce webhook handling
- github-webhooks - GitHub repository webhook handling
- resend-webhooks - Resend email webhook handling
- chargebee-webhooks - Chargebee billing webhook handling
- clerk-webhooks - Clerk auth webhook handling
- elevenlabs-webhooks - ElevenLabs webhook handling
- openai-webhooks - OpenAI webhook handling
- paddle-webhooks - Paddle billing webhook handling
- hookdeck-event-gateway - Webhook infrastructure that replaces your queue — guaranteed delivery, automatic retries, replay, rate limiting, and observability for your webhook handlers
Skill frontmatter
license: MIT
metadata: {"author"=>"hookdeck", "version"=>"0.1.0", "repository"=>"https://github.com/hookdeck/webhook-skills"}