Webhook解説:署名付きペイロードとリトライ
本番環境でWebhookが壊れる理由
Webhookエンドポイントを構築し、ローカルでテストして、すべてが動作しました。しかし本番環境では、プロバイダーが重複イベントを送信したり、エンドポイントがタイムアウトしたり、攻撃者がリクエストを偽装したりします。突然、統合は信頼性がなく安全でなくなります。
Webhookは概念的にシンプルです—イベントによってトリガーされるHTTPコールバック—が、本番グレードの実装にはセキュリティと信頼性の慎重な処理が必要です。このガイドでは、真正性を検証するための署名付きペイロードと、障害を処理するためのリトライ戦略という2つの重要な側面をカバーします。
Webhookとは何か?
Webhookはユーザー定義のHTTPコールバックです。ソースシステムでイベントが発生すると(例:支払いが成功)、提供したURLにイベントに関するデータを含むHTTP POSTリクエストを送信します。このプッシュモデルはポーリングよりも効率的です。
しかし、Webhookは課題をもたらします:
- セキュリティ:リクエストが正当な送信者からのものかどうかをどうやって知るのか?
- 信頼性:エンドポイントがダウンしているか遅い場合はどうするか?
- 重複:ネットワークがリトライを引き起こす可能性があり、同じイベントを複数回受信するかもしれません。
まずセキュリティに取り組みましょう。
署名付きペイロードでWebhookを保護する
署名付きペイロードは共有シークレットを使用してリクエスト本文の暗号署名を作成します。送信者はこの署名をヘッダー(例:X-Signature)に含めます。エンドポイントは署名を再計算して比較します。一致すれば、リクエストは真正です。
HMAC署名の仕組み
ほとんどのプロバイダーはHMAC-SHA256を使用します。署名は共有シークレットを使用して生のリクエスト本文に対して計算されます。フローは次のとおりです:
- プロバイダーとコンシューマーが秘密鍵を共有します。
- プロバイダーがペイロードを作成し、HMAC-SHA256(secret, payload)を計算してヘッダーで送信します。
- コンシューマーがリクエストを受信し、生の本文を読み取り、同じHMACを計算して比較します。
重要:受信した生の本文をそのまま使用してください—JSONを解析して再シリアライズするとバイトが変更され、署名が壊れる可能性があります。
署名検証の実装
Expressを使用したNode.jsの例を次に示します:
const crypto = require('crypto');
const express = require('express');
const app = express();
// Webhookルートには生のボディパーサーを使用
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-signature'];
const secret = process.env.WEBHOOK_SECRET;
const expected = crypto
.createHmac('sha256', secret)
.update(req.body)
.digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
return res.status(401).send('Invalid signature');
}
// イベントを処理
const event = JSON.parse(req.body);
// ... イベントを処理
res.status(200).send('OK');
});
タイミング攻撃を防ぐために、常にcrypto.timingSafeEqualのような定数時間比較を使用してください。
その他のセキュリティ考慮事項
- タイムスタンプ検証:署名付きペイロードにタイムスタンプを含め、古いリクエストを拒否してリプレイ攻撃を防ぎます。
- HTTPS:Webhookエンドポイントには常にHTTPSを使用してください。
- シークレットローテーション:ダウンタイムなしでローテーションできるように、複数のアクティブなシークレットをサポートします。
信頼性の高いリトライの実装
安全なエンドポイントでも、ネットワークの問題や一時的な障害によりWebhook配信が失敗する可能性があります。堅牢なリトライメカニズムにより、イベントが失われないようにします。
送信側のリトライ戦略
Webhook送信者を構築する場合は、ジッター付きの指数バックオフを実装します。例:
- リトライ1:1分後
- リトライ2:5分後
- リトライ3:30分後
- リトライ4:2時間後
- リトライ5:24時間後
サンダリングハード問題を避けるためにランダムなジッターを追加します。最大試行回数後に停止してアラートを出します。
受信側のベストプラクティス
Webhookコンシューマーとして、送信者のリトライポリシーを制御することはできませんが、エンドポイントを回復力のあるものにすることができます:
- 迅速に応答する:重い処理の前に2xxステータスで受信を確認します。キューを使用します。
- 冪等性:重複イベントを適切に処理します。イベントIDを使用して重複を排除します。
- 障害を監視する:障害をログに記録し、アラートを設定します。
冪等性で重複を処理する
Webhookプロバイダーはタイムアウト時にリトライすることが多いため、同じイベントを複数回受信する可能性があります。処理を冪等にします:
- 処理済みイベントIDを一意制約付きでデータベースに保存します。
- 処理前にIDが既に存在するか確認し、存在する場合は再処理せずに200 OKを返します。
- 状態変更操作には冪等キーを使用します。
データベースの一意インデックスを使用した例:
async function handleEvent(event) {
try {
await db.query('INSERT INTO processed_events (id) VALUES ($1)', [event.id]);
} catch (err) {
if (err.code === '23505') { // 一意制約違反
return; // 既に処理済み
}
throw err;
}
// イベントを処理
}
比較:Webhookセキュリティアプローチ
| アプローチ | 長所 | 短所 |
|---|---|---|
| HMAC署名 | 強力な整合性、広くサポート | シークレット管理が必要 |
| Basic認証 | シンプル | 安全性が低い、ヘッダーに認証情報 |
| IP許可リスト | 実装が簡単 | IPが変更される可能性、堅牢ではない |
HMAC署名はWebhookセキュリティのデファクトスタンダードです。
ローカルでWebhookをテストする
ngrokやlocaltunnelなどのツールは、テストのためにローカルサーバーをインターネットに公開します。署名検証とリトライロジックをシミュレートされた障害で常にテストしてください。
WebhookからのJSONペイロードを検査する場合、フォーマットするとデバッグに役立ちます。JSON Formatterを使用して、Webhookペイロードを整形して検証してください。
FAQ
Webhook署名を検証するにはどうすればよいですか?
共有シークレットを使用して生のリクエスト本文のHMACを計算し、定数時間比較関数を使用して署名ヘッダーと比較します。
Webhookエンドポイントがダウンしている場合はどうすればよいですか?
ほとんどのプロバイダーは指数バックオフでリトライします。エンドポイントが迅速に2xxを返し、非同期で処理するようにして、ダウンタイムの影響を最小限に抑えます。
署名なしでWebhookを使用できますか?
危険です。署名がないと、攻撃者がリクエストを偽装できます。常に署名付きペイロードを使用するか、少なくともHTTPS経由でBasic認証を使用してください。
結論
Webhookは強力ですが、セキュリティと信頼性に注意が必要です。HMAC署名検証を実装して真正性を確保し、リトライと重複を適切に処理するようにシステムを設計してください。これらの実践により、Webhook統合は堅牢で本番環境に対応できるようになります。