webhook-handler-patterns

Enforce verify-then-parse-then-idempotent processing for webhook handlers.

79|11|Updated Jan 30, 2026
One-click install
npx skills add https://github.com/hookdeck/webhook-skills --skill webhook-handler-patterns
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: webhook-handler-patterns
Source: https://github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns
Command: npx skills add https://github.com/hookdeck/webhook-skills --skill webhook-handler-patterns

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Webhook integrations are prone to security risks and duplicate processing due to retries. This Skill provides a concrete pattern to verify signatures before parsing payloads, parse after verification, and handle events idempotently, with robust error handling and retry strategies across Express, Next.js, and FastAPI.

Core Features & Use Cases

  • Verify-first, parse-second, idempotent-third processing sequence to prevent duplicates and ensure security.
  • Framework-specific guidance for Express, Next.js, and FastAPI with raw body handling and middleware order.
  • Patterns for error handling, retry logic, and observability to diagnose webhook issues in production.

Quick Start

Use this Skill to structure a Stripe-like webhook route so that the raw body is preserved for signature verification, the payload is parsed after verification, and duplicates are avoided through idempotent handling.

Frequently Asked Questions about webhook-handler-patterns

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I verify webhook signatures in Express before parsing the payload?

To verify webhook signatures in Express, you must preserve the raw body and enforce a verify-then-parse sequence. This prevents security risks by validating the sender before any payload processing occurs.

Why does my Next.js webhook handler fail signature verification?

Next.js webhook signature verification fails when middleware parses the body before verification. You must configure raw body handling to preserve the original payload for accurate signature validation.

What is the best way to handle duplicate webhook deliveries from retries?

The best way to handle duplicate webhook deliveries is idempotent processing. By enforcing a verify-then-parse-then-idempotent sequence, you ensure retried events do not result in duplicate side effects.

How do I implement retry logic and error handling for webhook routes in FastAPI?

Implement retry logic and error handling for FastAPI webhook routes by following structured patterns for observability and error strategies. This allows you to diagnose and recover from failed webhook deliveries in production.

Does this webhook handler pattern work with Stripe webhooks?

Yes, this pattern works for Stripe-like webhook routes. It structures your handler to preserve the raw body for signature verification, parse after validation, and avoid duplicates through idempotent handling.

When should I use idempotency in my webhook processing sequence?

You should use idempotency in your webhook processing sequence whenever providers implement automatic retries. Idempotent handling prevents duplicate processing of the same event, ensuring data consistency.