Webhook解説:署名付きペイロードとリトライ
決済プロバイダーやCI/CDサービスを統合したばかりで、リアルタイムのイベントを受け取る必要があるとします。Webhookはシステム間でデータをプッシュする標準的な方法ですが、多くの実装がセキュリティ上の欠陥や信頼性の低い配信によって本番環境で失敗しています。このガイドでは、署名付きペイロードでWebhookを安全に保護し、堅牢なリトライ機構を実装する方法を説明します。
Webhookとは何か、なぜ重要なのか
WebhookはHTTPコールバックです。ソースシステムでイベント(例:新規注文)が発生すると、指定したURLにHTTP POSTリクエストを送信します。ポーリングとは異なり、Webhookは効率的でほぼリアルタイムです。ただし、HTTPベースであるため、セキュリティと信頼性を明示的に処理する必要があります。
一般的なユースケースには、決済通知、CI/CDパイプラインのトリガー、チャット通知、SaaSアプリケーション間のデータ同期などがあります。
署名付きペイロードでWebhookを保護する
Webhookは公開アクセス可能なエンドポイントであるため、攻撃者が偽のリクエストを送信できます。これを防ぐため、プロバイダーは秘密鍵で各ペイロードに署名します。受信側は署名を検証して、真正性と完全性を確保します。
HMAC署名の仕組み
最も一般的な方法はHMAC-SHA256です。プロバイダーは共有シークレットを使用してリクエストボディのハッシュを計算し、それをヘッダー(例:X-Signature)に含めます。受信側はハッシュを再計算して比較します。
// Node.js example: generating a signature
const crypto = require('crypto');
const secret = 'your_webhook_secret';
const payload = JSON.stringify({ event: 'order.created', id: 123 });
const signature = crypto.createHmac('sha256', secret).update(payload).digest('hex');
// Send signature in header: X-Signature: sha256=...
受信側での署名検証
タイミング攻撃を防ぐため、常に定数時間比較を使用してください。Node.jsではcrypto.timingSafeEqualを使用します。
// Express.js middleware example
const crypto = require('crypto');
function verifySignature(req, res, next) {
const signature = req.headers['x-signature'];
const payload = JSON.stringify(req.body); // raw body needed
const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
const trusted = Buffer.from(`sha256=${expected}`, 'utf8');
const received = Buffer.from(signature, 'utf8');
if (trusted.length !== received.length || !crypto.timingSafeEqual(trusted, received)) {
return res.status(401).send('Invalid signature');
}
next();
}
重要:検証には解析済みのJSONではなく、生のリクエストボディを使用して、不一致を避けてください。
追加のセキュリティ対策
- タイムスタンプの検証:署名にタイムスタンプを含め、数分以上前のリクエストを拒否してリプレイ攻撃を防ぎます。
- HTTPSのみ:転送中のデータを保護するため、常にHTTPSエンドポイントを使用します。
- IP許可リスト:プロバイダーがIP範囲を公開している場合は、受信リクエストをそれらのIPに制限します。
信頼性の高いリトライの実装
Webhookはネットワークの問題、サーバーダウン、バグなどで失敗する可能性があります。プロバイダーは通常、指数バックオフで失敗した配信をリトライします。受信側は冪等性を確保し、重複イベントを処理する必要があります。
冪等性のための設計
各Webhookイベントには一意のIDが必要です。処理済みのIDを保存して重複を無視します。一意制約を持つデータベースやRedisなどのキャッシュを使用します。
// Pseudocode for idempotent processing
if (await redis.exists(`webhook:${event.id}`)) {
return res.status(200).send('Already processed');
}
await processEvent(event);
await redis.set(`webhook:${event.id}`, '1', 'EX', 86400); // 24h TTL
リトライ戦略
プロバイダーは通常、遅延を増やしながらリトライします(例:1秒、5秒、30秒、5分、1時間)。タイムアウトを避けるため、エンドポイントが迅速に(5秒以内に)応答するようにしてください。処理に時間がかかる場合は、受信を確認して非同期で処理します。
一般的なリトライパターンの比較は次のとおりです。
| パターン | 長所 | 短所 |
|---|---|---|
| 固定間隔 | シンプル | 復旧中のサーバーに負荷をかけ続ける可能性 |
| 指数バックオフ | 障害時の負荷を軽減 | 一時的なエラーで配信が遅延 |
| ジッター付き指数バックオフ | サンダリングハードを防止 | やや複雑 |
モニタリングとデッドレターキュー
すべてのWebhook試行と失敗をログに記録します。最大リトライ回数に達した後、イベントを手動検査用のデッドレターキュー(DLQ)に移動します。高い失敗率に対してアラートを設定します。
全体をまとめる:ステップバイステップの実装
- HTTPSエンドポイントを設定し、POSTリクエストを受け付けて生のボディを読み取ります。
- 署名を検証します。共有シークレットと定数時間比較を使用します。
- タイムスタンプを確認してリプレイ攻撃を防ぎます(提供されている場合)。
- 冪等性を確保します。イベントIDをキャッシュまたはデータベースと照合します。
- イベントを非同期で処理します(時間がかかる可能性がある場合)。すぐに200 OKで応答します。
- 送信側でリトライロジックを実装します。指数バックオフとジッターを使用します。
- モニタリングとアラートを設定し、永続的なエラーにはDLQを使用します。
FAQ
署名付きWebhookペイロードとは何ですか?
署名付きペイロードには暗号署名(通常はHMAC)が含まれ、受信側はリクエストが信頼できる送信元から来たもので改ざんされていないことを検証できます。
重複したWebhookイベントを処理するにはどうすればよいですか?
ペイロードに含まれる一意のイベントIDを使用して、処理済みイベントを追跡します。重複を無視するため、TTL付きでIDをデータベースまたはキャッシュに保存します。
Webhookエンドポイントは何を返すべきですか?
受信を確認するため、2xxステータスコード(例:200 OK)を迅速に返します。処理が失敗した場合は5xxを返してリトライをトリガーしますが、一時的なエラーの場合のみにしてください。
Webhookペイロードをテストする際、JSON構造を検査する必要があるかもしれません。JSON Formatterを使用して、デバッグを容易にするためにWebhookペイロードを検証し整形表示してください。