webhook-handler-patterns

Webhook ハンドラーパターン

このスキルを使用する場面

• Webhook ハンドラーの適切な順序（検証 → 解析 → 冪等性を保って処理）に従う
• 冪等性を備えた Webhook ハンドラーを実装する
• エラーを処理し、再試行の動作を設定する
• フレームワーク固有の注意点（raw body、ミドルウェアの順序）を理解する
• 本番環境に対応した Webhook インフラストラクチャを構築する

リソース

ハンドラーの順序

• references/handler-sequence.md - まず検証し、次に解析し、最後に冪等性を保って処理します

ベストプラクティス

• references/idempotency.md - 重複処理を防止します
• references/error-handling.md - 戻りコード、ログ記録、デッドレターキュー
• references/retry-logic.md - プロバイダーの再試行スケジュール、バックオフパターン

フレームワークガイド

• references/frameworks/express.md - Express.js のパターンと注意点
• references/frameworks/nextjs.md - Next.js App Router のパターン
• references/frameworks/fastapi.md - FastAPI/Python のパターン

クイックリファレンス

ハンドラーの順序

1. まず署名を検証します — raw body を使用し、無効なリクエストは 4xx で拒否します。
2. 次にペイロードを解析します — 検証後にイベントを解析するか、イベントを構築します。
3. 最後に冪等性を保って処理します — イベント ID を確認してから処理し、重複の場合は 2xx を返します。

詳細と、プロバイダーの検証および冪等性パターンへのリンクについては、references/handler-sequence.md を参照してください。

応答コード

コード	意味	プロバイダーの動作
2xx	成功	再試行しません
4xx	クライアントエラー	通常は再試行しません（429 を除く）
5xx	サーバーエラー	バックオフして再試行します
429	レート制限	遅延後に再試行します

冪等性チェックリスト

1. ペイロードから一意のイベント ID を抽出します
2. イベントがすでに処理されているか確認します
3. トランザクション内でイベントを処理します
4. 処理が成功した後にイベント ID を保存します
5. 重複イベントには成功を返します

関連スキル

• stripe-webhooks - Stripe の決済 Webhook 処理
• shopify-webhooks - Shopify の E コマース Webhook 処理
• github-webhooks - GitHub リポジトリの Webhook 処理
• resend-webhooks - Resend のメール Webhook 処理
• chargebee-webhooks - Chargebee の請求 Webhook 処理
• clerk-webhooks - Clerk の認証 Webhook 処理
• elevenlabs-webhooks - ElevenLabs の Webhook 処理
• openai-webhooks - OpenAI の Webhook 処理
• paddle-webhooks - Paddle の請求 Webhook 処理
• hookdeck-event-gateway - キューを置き換える Webhook インフラストラクチャ — 配信保証、自動再試行、再生、レート制限、および Webhook ハンドラーの可観測性