Webhook解説:署名付きペイロードと信頼性の高いリトライ
決済連携をリリースし、ステージングではすべて問題なく動作していました。ところが本番環境で顧客が支払いを済ませた後、あなたのエンドポイントが2秒間タイムアウトし、注文が有効化されないままになります。一方で決済プロバイダーは同じイベントを3回リトライし、アプリは成功した1件に対して3つの重複注文を作成してしまいます。Webhookは一見シンプルに見えます — ただのHTTP POSTです — しかし難しいのは信頼性と配信保証です。
この記事では、Webhook連携で最も頻繁に問題となる2つの点を扱います。リクエストが本当に送信元から来たものかを検証すること、そして副作用を重複させずにリトライを処理することです。
Webhookとは実際何か
Webhookは逆方向のAPI呼び出しです。サーバーが毎分プロバイダーに「何か新しいことは?」とポーリングする代わりに、イベントが発生したときにプロバイダーが登録したURLへHTTPリクエストをプッシュします。ペイロードは通常JSONで、イベントタイプはボディかヘッダーのどちらかに含まれます。
POST /webhooks/payments HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-Event-Id: evt_8f2c1a
X-Timestamp: 1735689600
X-Signature: t=1735689600,v1=5d41402abc4b2a76b9719d911017c592
{
"id": "evt_8f2c1a",
"type": "payment.succeeded",
"created": 1735689600,
"data": { "order_id": "ord_123", "amount": 4999, "currency": "USD" }
}送信側の設計上の2つの決定事項があり、どのプロバイダーを評価する際にも両方を確認すべきです。ペイロードに署名しているか、失敗時にリトライするかです。
署名なしのWebhookが危険な理由
WebhookのURLは公開されています。URLを知った誰もが偽のpayment.succeededイベントをPOSTし、未払いの注文を支払い済みにできてしまいます。IP許可リストは多少役立ちますが、プロバイダーはIPを変更し、CDNの背後で動作し、安定したリストが得られないこともあります。
堅牢な解決策は、あなたとプロバイダーだけが知る共有シークレットを使った、生のリクエストボディに対するHMAC署名です。プロバイダーが署名を計算してヘッダーで送信し、あなたが再計算して比較します。
署名を正しく検証する
間違えやすい3つのポイントがあります:
- 生のボディを使う。 JSONの解析は検証後に行います。解析済みオブジェクトを再シリアライズすると空白やキーの順序が変わり、署名が一致しなくなります。
- 定数時間で比較する。 単純な文字列比較はタイミング情報を漏洩します。タイミングセーフな関数を使用してください。
- 署名対象の文字列にタイムスタンプを含める。
timestamp.bodyに署名することで、古いリクエストを拒否し、リプレイ攻撃を防げます。
// Node.js / Express の例
const crypto = require('crypto');
function verifySignature(rawBody, header, secret, toleranceSeconds = 300) {
const parts = Object.fromEntries(
header.split(',').map(p => p.split('='))
);
const timestamp = Number(parts.t);
if (!timestamp) return false;
// 古いリクエストを拒否(リプレイ対策)
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - timestamp) > toleranceSeconds) return false;
const expected = crypto
.createHmac('sha256', secret)
.update(`${parts.t}.${rawBody}`)
.digest('hex');
const a = Buffer.from(expected);
const b = Buffer.from(parts.v1 || '');
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
app.post('/webhooks/payments', express.raw({ type: '*/*' }), (req, res) => {
if (!verifySignature(req.body.toString(), req.get('X-Signature'), SECRET)) {
return res.status(401).send('invalid signature');
}
const event = JSON.parse(req.body.toString());
// ... イベント処理
res.status(200).send('ok');
});express.raw()ミドルウェアに注目してください。このルートの前にexpress.json()をマウントすると、ボディはすでに解析済みとなり署名チェックが静かに失敗します — 非常によくあるバグです。
イベントを失わないリトライの設計
Webhookの配信はat-least-onceであり、exactly-onceではありません。ネットワークは失敗し、デプロイでコンテナが再起動し、プロバイダーはあなたの200レスポンスが本当だったか知る由もありません。そのためプロバイダーは指数バックオフでリトライし、しばしば数時間から数日に及びます。
素早く応答し、後で処理する
エンドポイントは最小限の処理にとどめるべきです:検証、生イベントの永続化、2xxの返却。メール送信、他のAPI呼び出し、請求書生成といった重い処理はバックグラウンドジョブで行います。処理がプロバイダーのタイムアウトより長くかかると、実際には処理を完了していてもリクエストは失敗とみなされリトライされます。
- 署名とタイムスタンプを検証する。
- イベントIDに一意制約を付けたテーブルにイベントを挿入する。
- すぐに
200を返す。 - 保存したイベントを非同期で処理し、完了としてマークする。
冪等性:重複に対する本当の解決策
リトライが発生する以上、ハンドラーは2回実行しても安全でなければなりません。イベントIDが自然な冪等性キーです。
INSERT INTO webhook_events (event_id, type, payload, received_at)
VALUES ($1, $2, $3, now())
ON CONFLICT (event_id) DO NOTHING;挿入が0行に影響した場合、このイベントは以前に見たものです — 確認応答して先に進みます。ビジネスロジックにも同じ考え方を適用します:支払いを有効化する際に注文IDを一意キーとして使えば、2番目のイベントが2番目の有効化を作成することはできません。
ステータスコードを意図的に選ぶ
| ステータス | プロバイダーの動作 | 使用する場面 |
|---|---|---|
| 200 / 204 | 配信済みとしてマーク | イベントを受け付けた(処理済みでも) |
| 400 | 通常リトライしない | 到底処理できない不正なペイロード |
| 401 | 通常リトライしない | 署名の不一致 — シークレットを確認 |
| 429 | バックオフでリトライ | レート制限中 |
| 500 / 503 | バックオフでリトライ | 一時的な障害、DBダウン、デプロイ中 |
保存できなかったイベントに200を返すのは最悪の選択です:プロバイダーはリトライを止め、イベントは永久に失われます。5xxを返してリトライに任せましょう。
本番環境のための実践チェックリスト
- HTTPSのみを使用し、平文HTTPでのWebhookは決して受け付けない。
- 署名シークレットをシークレットマネージャーに保存し、ローテーションをサポートする — 多くのプロバイダーは2つのアクティブなシークレットを許可しています。
- すべてのリクエストについてイベントID、タイプ、署名結果、処理結果をログに記録する。
- リプレイを防ぐため許容時間枠(通常5分)を設定する。
- ハンドラーをアプリケーションコードだけでなくデータベースレベルで冪等にする。
- 失敗率や処理遅延がしきい値を超えたらアラートを出す。
- サポートスタッフ向けに手動リプレイエンドポイントを提供する。
ローカルでWebhookをテストする
localhostで公開POSTを簡単に受け取ることはできません。選択肢としては、開発ポートを公開するトンネリングツール、プロバイダーのCLIがあればそれ、または検証パスを試せるように署名付きペイロードをハンドラーに送る小さなスクリプトです。
最も価値のあるテストは重複です:同じイベントを2回送信し、システムが同じ状態になることを確認します。次に古いタイムスタンプのイベントを送信し、拒否されることを確認します。そしてボディの1バイトを改ざんし、署名チェックが失敗することを確認します。
ペイロードのデバッグ
WebhookのボディはJSONであり、不正な形式や深くネストしたペイロードはログで読むのが苦痛です。フォーマッターは解析コードを書く前に構造を素早く確認するのに役立ちます。JSONフォーマッターはブラウザで動作するため、顧客データをサーバーに送信せずにキャプチャしたペイロードを貼り付けることができます。
FAQ
WebhookとAPIの違いは何ですか?
APIはプルベースです:データが必要なときにあなたのコードがプロバイダーを呼び出します。Webhookはプッシュベースです:イベントが発生したときにプロバイダーがあなたのエンドポイントを呼び出します。ほとんどの連携は両方を使用します — イベント通知にはWebhook、詳細の取得やアクションの実行にはAPIです。
HMAC署名がどうしても一致しないのはなぜですか?
よくある原因は、生のバイトではなく再シリアライズしたボディに署名していることです。空白、キーの順序、Unicodeエスケープはすべてハッシュを変えます。JSONミドルウェアの前に生のリクエストボディを読み取り、シークレットとハッシュアルゴリズムがプロバイダーのドキュメントと一致することを確認してください。
Webhookのリトライは保証されていますか?
いいえ。プロバイダーは通常、指数バックオフで限られた期間リトライし、その後諦めます。Webhookは真実の源ではなく高速な通知チャネルとして扱い、プロバイダーのAPIと定期的に照合して見逃したイベントが最終的に修正されるようにしましょう。
今日Webhookレシーバーを構築またはデバッグしているなら、まず署名検証と冪等なストレージを固めることから始めてください — この2つの変更で、現実世界のWebhookインシデントの大半を排除できます。