webhook-handler-patterns — Claude Code skill: how it works
Teaches your coding agent to handle webhooks safely: verify raw payload signatures, enforce idempotency, and return proper status codes in Express, Next.js, or FastAPI.
npx skills add hookdeck/webhook-skills --skill webhook-handler-patterns -a claude-codeWhat webhook-handler-patterns does
The skill enforces a strict webhook handling order: verify the raw body signature first, parse the payload second, and process the event idempotently. To avoid duplicate operations, it checks unique event IDs inside database transactions. Duplicate deliveries receive a 2xx response.
It includes reference files for response status codes, retry backoff strategies, and specific frameworks like Express, Next.js App Router, and FastAPI. Signature verification breaks if an upstream parser converts the incoming body to JSON before checking HMAC signatures. The skill addresses this middleware gotcha directly.
What it helps with
- enforce strict signature verification using raw request bodies
- prevent duplicate event execution with database transaction checks
- configure proper HTTP status codes to control provider retry schedules
- resolve middleware ordering issues in Express, Next.js, and FastAPI
Example prompts for the agent
- Write an Express webhook handler that verifies HMAC signatures using the raw body
- Implement an idempotent webhook route in Next.js App Router checking event IDs
- Set up a FastAPI webhook endpoint with proper HTTP status codes for provider retries
How to install webhook-handler-patterns
1Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill webhook-handler-patterns -a claude-code2Manually: put the files in place
~/.claude/skills/webhook-handler-patterns/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/webhook-handler-patterns/
1Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill webhook-handler-patterns -a codex2Manually: put the files in place
.agents/skills/webhook-handler-patterns/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill webhook-handler-patterns -a cursor2Manually: put the files in place
.cursor/skills/webhook-handler-patterns/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install hookdeck/webhook-skills webhook-handler-patterns2Manually: put the files in place
.github/skills/webhook-handler-patterns/SKILL.md1Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill webhook-handler-patterns -a gemini-cli2Platform CLI
gemini skills install https://github.com/hookdeck/webhook-skills --path skills/webhook-handler-patternsManually: put the files in place
.devin/skills/webhook-handler-patterns/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill webhook-handler-patterns -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about webhook-handler-patterns
How to install webhook-handler-patterns in Claude Code?
Run npx skills add hookdeck/webhook-skills --skill webhook-handler-patterns -a claude-code in your terminal. The files will be placed into ~/.claude/skills/webhook-handler-patterns/SKILL.md.
What does webhook-handler-patterns do?
It guides AI coding agents through reliable webhook patterns: verifying payloads before parsing, handling duplicate events idempotently, and configuring correct HTTP responses.
How does the skill handle duplicate webhook deliveries?
It checks the unique event ID within a database transaction and returns a 2xx success code for duplicates so the provider stops retrying.
Source text
SKILL.md · MIT
--- 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 - [references/handler-sequence.md](references/handler-sequence.md) - Verify first, parse second, handle idempotently third ### Best Practices - [references/idempotency.md](references/idempotency.md) - Prevent duplicate processing - [references/error-handling.md](references/error-handling.md) - Return codes, logging, dead letter queues - [references/retry-logic.md](references/retry-logic.md) - Provider retry schedules, backoff patterns ### Framework Guides - [references/frameworks/express.md](references/frameworks/express.md) - Express.js patterns and gotchas - [references/frameworks/nextjs.md](references/frameworks/nextjs.md) - Next.js App Router patterns - [references/frameworks/fastapi.md](references/frameworks/fastapi.md) - FastAPI/Python patterns ## Quick Reference ### Handler Sequence 1. **Verify signature first** — Use raw body; reject invalid requests with 4xx. 2. **Parse payload second** — After verification, parse or construct the event. 3. **Handle idempotently third** — Check event ID, then process; return 2xx for duplicates. See [references/handler-sequence.md](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 1. Extract unique event ID from payload 2. Check if event was already processed 3. Process event within transaction 4. Store event ID after successful processing 5. Return success for duplicate events ## Related Skills - [stripe-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/stripe-webhooks) - Stripe payment webhook handling - [shopify-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/shopify-webhooks) - Shopify e-commerce webhook handling - [github-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/github-webhooks) - GitHub repository webhook handling - [resend-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/resend-webhooks) - Resend email webhook handling - [chargebee-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/chargebee-webhooks) - Chargebee billing webhook handling - [clerk-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/clerk-webhooks) - Clerk auth webhook handling - [elevenlabs-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/elevenlabs-webhooks) - ElevenLabs webhook handling - [openai-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/openai-webhooks) - OpenAI webhook handling - [paddle-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/paddle-webhooks) - Paddle billing webhook handling - [hookdeck-event-gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway) - Webhook infrastructure that replaces your queue — guaranteed delivery, automatic retries, replay, rate limiting, and observability for your webhook handlers
© hookdeck · MIT · hookdeck/webhook-skills
