IT 技書の森

Webhook

イベント発生時にサーバーが指定された URL に HTTP リクエストを送信する、プッシュ型の通知メカニズム

APIイベント駆動

Webhook とは

Webhook は、イベントが発生した際にサーバーが事前に登録された URL に HTTP POST リクエストを送信するプッシュ型の通知メカニズムである。「逆 API」とも呼ばれ、クライアントがポーリングする代わりに、サーバーがクライアントに通知する。

GitHub の Push イベント、Stripe の支払い完了、Slack のメッセージ投稿など、SaaS の連携で広く使われている。

ポーリングとの比較

ポーリング: クライアントが定期的に「新しいデータある？」と問い合わせ
  [クライアント] → GET /events → [サーバー] → "なし"
  [クライアント] → GET /events → [サーバー] → "なし"
  [クライアント] → GET /events → [サーバー] → "あり!"

Webhook: サーバーがイベント発生時に通知
  [サーバー] → POST /webhook → [クライアント] → "受信!"
観点 Webhook ポーリング
リアルタイム性 即座 ポーリング間隔に依存
サーバー負荷 イベント時のみ 定期的にリクエスト
実装の複雑さ 受信エンドポイントが必要 シンプル
信頼性 配信失敗のリトライが必要 確実に取得できる

セキュリティ

署名検証

Webhook の送信元が正当であることを確認するため、HMAC 署名を検証する。

import { createHmac } from 'crypto';

function verifySignature(body: string, signature: string, secret: string): boolean {
  const expected = 'sha256=' + createHmac('sha256', secret).update(body).digest('hex');
  return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

べき等性

Webhook は同じイベントが複数回配信される可能性がある (at-least-once)。イベント ID で重複を検出し、べき等に処理する。

信頼性の確保

Webhook の配信が失敗した場合のリトライ戦略:

  1. 即座にリトライ (1 回)
  2. 指数バックオフでリトライ (1 分、5 分、30 分)
  3. 最大リトライ回数に達したら DLQ に移動
  4. 管理画面で手動再送を提供

SQS を挟むパターン

Webhook を直接処理すると、処理が遅い場合にタイムアウトする。SQS を挟んで非同期処理にする。

[外部サービス] → POST → [API Gateway] → [Lambda A: SQS に送信] → 200 OK
                                          ↓
                                        [SQS] → [Lambda B: 実際の処理]

実務での活用方法は関連書籍にも詳しい。

関連用語