AgentSkillsCN

webhook-handler-patterns

Webhook 处理程序的最佳实践。适用于实施处理程序的顺序（先验证、再解析、最后幂等处理）、幂等性、错误处理、重试逻辑，或针对 Express、Next.js、FastAPI 等框架特有的问题时使用。

SKILL.md
--- frontmatter
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

  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 for details and links to provider verification and idempotency patterns.

Response Codes

CodeMeaningProvider Behavior
2xxSuccessNo retry
4xxClient errorUsually no retry (except 429)
5xxServer errorRetry with backoff
429Rate limitedRetry 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