Back to Details

webhook-handler-patterns

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Webhook Handler Patterns

Webhook处理器模式

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
  • 遵循正确的Webhook处理器顺序（验证→解析→幂等处理）
  • 实现幂等的Webhook处理器
  • 处理错误并配置重试行为
  • 了解特定框架的注意事项（原始请求体、中间件顺序）
  • 构建生产就绪的Webhook基础设施

Resources

参考资源

Handler Sequence

处理器流程

  • references/handler-sequence.md - Verify first, parse second, handle idempotently third
  • references/handler-sequence.md - 先验证，再解析，最后幂等处理

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
  • references/idempotency.md - 防止重复处理
  • references/error-handling.md - 返回码、日志、死信队列
  • references/retry-logic.md - 服务商重试计划、退避模式

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
  • references/frameworks/express.md - Express.js模式与注意事项
  • references/frameworks/nextjs.md - Next.js App Router模式
  • references/frameworks/fastapi.md - FastAPI/Python模式

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.
  1. 先验证签名 — 使用原始请求体；对无效请求返回4xx状态码拒绝。
  2. 再解析负载 — 验证通过后，解析或构建事件。
  3. 最后幂等处理 — 检查事件ID，再进行处理；对重复事件返回2xx状态码。
详情及服务商验证与幂等模式相关链接，请查看references/handler-sequence.md。

Response Codes

响应码

CodeMeaningProvider Behavior
2xx
SuccessNo retry
4xx
Client errorUsually no retry (except 429)
5xx
Server errorRetry with backoff
429
Rate limitedRetry after delay
状态码含义服务商行为
2xx
成功不重试
4xx
客户端错误通常不重试（429除外）
5xx
服务器错误退避重试
429
请求受限延迟后重试

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
  1. 从负载中提取唯一事件ID
  2. 检查事件是否已处理过
  3. 在事务中处理事件
  4. 处理成功后存储事件ID
  5. 对重复事件返回成功状态

Related Skills

相关技能