Claude CodeでWebhookを実装する方法！イベント駆動アーキテクチャを自動構築する手順

はじめに

「StripeやGitHubのWebhookを受け取る処理の書き方がわからない」

「Webhookの署名検証を実装したいが、各サービスごとに仕様が異なる」

「Webhookの処理に失敗したときのリトライ戦略がわからない」

Webhookは外部サービスとのリアルタイム連携に欠かせない仕組みですが、署名検証・べき等性・リトライなど実装すべき項目が多くあります。Claude Codeを使えば、堅牢なWebhook処理を体系的に実装できます。

目次

1. Webhookの基本アーキテクチャ
2. Webhookエンドポイントの実装
3. 署名検証の実装
4. 主要サービスのWebhook受信
5. イベント処理のキュー設計
6. べき等性の実装
7. リトライとデッドレターキュー
8. Webhookの送信側の実装
9. まとめ

1. Webhookの基本アーキテクチャ

アーキテクチャの設計相談

> 以下のWebhook受信処理のアーキテクチャを設計してください。

  受信するWebhook：
  - Stripe（決済イベント）
  - GitHub（PR・push・issue）
  - Slack（コマンド・インタラクション）

  要件：
  - 高い可用性（Webhookの取りこぼしゼロ）
  - 処理の冪等性（同じイベントを2回処理しない）
  - 重い処理は非同期で実行
  - 処理ログの永続化

  適切なアーキテクチャとメッセージキューの選択を提案してください。

イベント駆動設計のフロー

外部サービス → Webhookエンドポイント
               ↓ 即時応答（200 OK）
               ↓ 署名検証
               ↓ イベントをキューに保存
               ↓
            ワーカー → イベント処理
                       ↓ 成功：完了ログ保存
                       ↓ 失敗：リトライキューへ

2. Webhookエンドポイントの実装

基本的なWebhookエンドポイント

> 汎用的なWebhookエンドポイントを実装してください。

  フレームワーク：Express（またはFastAPI）

  実装内容：
  - Raw bodyの取得（署名検証に必要）
  - 各サービスの署名検証
  - イベントのデータベースへの保存
  - 非同期処理キューへの投入
  - 200レスポンスの即時返却（タイムアウト防止）
  - 重複イベントの検出（event_idによる重複排除）

  処理全体が5秒以内に完了するよう設計してください。

3. 署名検証の実装

Stripe Webhookの署名検証

> Stripe Webhookの署名検証を実装してください。

  実装内容：
  - stripe-signatureヘッダーの検証
  - Stripe SDKのwebhooks.constructEventの使用
  - タイムスタンプの有効期限チェック（リプレイ攻撃防止）
  - 検証失敗時の400レスポンス

  TypeScriptで型安全に実装してください。

GitHub Webhookの署名検証

> GitHub Webhookの署名検証（HMAC-SHA256）を実装してください。

  実装内容：
  - X-Hub-Signatureヘッダーの検証
  - 定数時間比較（タイミング攻撃防止）
  - シークレットの環境変数管理

  また、受信したいイベント種別（X-GitHub-Eventヘッダー）を
  ルーティングする仕組みも実装してください。

汎用的な署名検証ユーティリティ

> 複数サービスの署名検証を統一的に扱う
  ユーティリティを実装してください。

  対応サービス：
  - Stripe（HMAC-SHA256・タイムスタンプ検証）
  - GitHub（HMAC-SHA256）
  - Slack（HMAC-SHA256・タイムスタンプ検証）
  - Shopify（HMAC-SHA256）

  サービスを追加しやすい拡張可能な設計にしてください。

4. 主要サービスのWebhook受信

Stripe決済イベントの処理

> Stripeの主要Webhookイベントを処理するハンドラーを実装してください。

  処理するイベント：
  - checkout.session.completed → 注文確定・メール送信
  - customer.subscription.created → サブスクリプション有効化
  - customer.subscription.deleted → サービス停止処理
  - invoice.payment_failed → 決済失敗の通知・リトライ管理
  - charge.refunded → 返金処理

  各イベントの処理を独立したハンドラー関数として実装してください。

GitHub Actions連携

> GitHub Webhookを受信してCI/CDをトリガーする処理を実装してください。

  トリガー条件：
  - PRがmainにマージされたら本番デプロイを開始
  - issueにlabel:deployが付いたらステージングにデプロイ
  - 特定ブランチへのpushでテスト環境を更新

  処理内容：
  - GitHub APIでデプロイメントを作成
  - デプロイ完了後にPRにコメントを投稿

5. イベント処理のキュー設計

BullMQを使ったジョブキュー

> BullMQを使ってWebhookイベントのジョブキューを構築してください。

  設計：
  - Webhookエンドポイントがジョブを即時キューに追加
  - ワーカーが非同期でジョブを処理
  - 優先度の設定（Stripeの決済イベントは高優先度）
  - 同時実行数の制限

  設定内容：
  - 最大リトライ回数：3回
  - バックオフ戦略：指数バックオフ（1分→5分→30分）
  - 完了ジョブの保持期間：24時間
  - 失敗ジョブのデッドレターキュー

6. べき等性の実装

イベントの重複処理防止

> Webhook処理のべき等性を実装してください。

  戦略：
  - イベントIDをデータベースに保存
  - 処理前に重複チェック（SELECT FOR UPDATE）
  - 処理中・処理済みの状態管理

  以下のケースを考慮してください：
  - 同じイベントが2回届いた場合
  - 処理中にクラッシュした場合の再実行
  - 複数のワーカーが同じイベントを処理しようとした場合

7. リトライとデッドレターキュー

失敗処理の設計

> Webhook処理の失敗リトライとデッドレターキューを実装してください。

  リトライ戦略：
  - 即時リトライ：1回
  - 遅延リトライ：1分後・5分後・30分後（指数バックオフ）
  - 最終失敗後：デッドレターキューに移動

  デッドレターキューの処理：
  - 管理画面から失敗イベントを確認できる
  - 手動で再処理をトリガーできる
  - アラート通知（Slack）

8. Webhookの送信側の実装

自社サービスからのWebhook送信

> 自社APIからユーザーが登録したWebhookエンドポイントに
  イベントを送信する仕組みを実装してください。

  機能：
  - エンドポイントの登録・管理API
  - HMAC-SHA256による署名付き送信
  - タイムアウト設定（5秒）
  - リトライ処理（失敗時に3回まで）
  - 送信ログの保存
  - 管理画面でのWebhookログ確認

まとめ

Claude CodeでのWebhook実装の効率化ポイント：

• 複数サービスの署名検証を一括実装できる
• キュー設計・べき等性・リトライを体系的に実装できる
• 送信側のWebhookシステムも自動構築できる

Webhook実装で必須の要素：

1. 署名検証（セキュリティ）
2. 200レスポンスの即時返却（タイムアウト防止）
3. べき等性（重複処理防止）
4. 非同期処理（重い処理の切り離し）
5. リトライ・デッドレター（信頼性確保）

次回の第37回：React Nativeでモバイルアプリ開発では、クロスプラットフォーム開発をClaude Codeで効率化する方法を解説します。

よくある質問（FAQ）

Q. ローカル開発中にWebhookをテストする方法はありますか？

A. ngrokやCloudflare Tunnelを使ってローカルサーバーを外部に公開することで、外部サービスからのWebhookを受け取れます。Claude Codeに「ngrokを使ってStripeのWebhookをローカルでテストする方法を教えてください」と依頼できます。

この記事はClaude Code入門シリーズ（第4部）の第36回です。← 第35回：モノレポ管理 ｜ 第37回：React Native →

ご質問はお問い合わせページからお気軽にどうぞ。