Webhook handler patterns
Skill hookdeck/webhook-skills/skills/webhook-handler-patterns
Webhook integration skills for AI coding agents (Claude Code, Cursor, Copilot). Step-by-step guidance for setting up webhook receivers, signature verification, and event handling for Stripe, Shopify, GitHub, and more. Built on the Agent Skills specification.
npx -y skills add hookdeck/webhook-skills --skill webhook-handler-patternsAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
What its author says it does
Copied from the file, not written here
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.
The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.
SKILL.md
3.9 KB, as published. Nobody here has run it
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