Webhook解説:署名付きペイロードとリトライ戦略
イベントを外部サービスに通知するためにWebhookを送信するAPIを構築したとします。しかし、受信エンドポイントがダウンしている場合はどうなるでしょうか?悪意のある攻撃者がWebhookリクエストを偽造しようとした場合は?適切な保護措置がないと、Webhookはデータの不整合やセキュリティ脆弱性の原因になり得ます。この記事では、署名付きペイロードとリトライメカニズムを実装して、Webhookを信頼性が高く安全にする方法を説明します。
Webhookとは何か、なぜセキュリティが必要なのか?
Webhookは、特定のイベントによってトリガーされるユーザー定義のHTTPコールバックです。これにより、注文が行われたときに決済サービスに通知するなど、システム間のリアルタイム通信が可能になります。しかし、Webhookは公開アクセス可能なエンドポイントであるため、なりすましやリプレイ攻撃に対して脆弱です。さらに、ネットワークの問題や受信側のダウンタイムにより、イベントが失われる可能性があります。したがって、2つの重要な側面に対処する必要があります:真正性(署名付きペイロードによる)と信頼性(リトライによる)です。
署名付きペイロード:真正性と完全性の確保
署名付きペイロードを使用すると、受信者はWebhookが信頼できる送信元から発信されたものであり、データが改ざんされていないことを検証できます。これは通常、共有シークレットを使用したHMAC(Hash-based Message Authentication Code)によって実現されます。
HMAC署名の仕組み
送信者と受信者は秘密鍵を共有します。各Webhookリクエストに対して、送信者は秘密鍵とリクエストペイロード(リプレイ攻撃を防ぐためにタイムスタンプを含めることが多い)を使用してHMAC署名を計算します。署名はX-Signatureなどのヘッダーで送信されます。受信者は署名を再計算し、受信した署名と比較します。一致すれば、リクエストは本物です。
以下は、HMAC-SHA256を使用したPythonの例です:
import hmac
import hashlib
import time
secret = b'your_shared_secret'
payload = b'{"event":"order.created","id":123}'
timestamp = str(int(time.time())).encode()
message = timestamp + b'.' + payload
signature = hmac.new(secret, message, hashlib.sha256).hexdigest()
# ヘッダーを送信: X-Signature: signature, X-Timestamp: timestamp
受信側では、署名を検証し、タイムスタンプをチェックしてリクエストが最近のもの(例:5分以内)であることを確認します。これによりリプレイ攻撃を防ぎます。
署名付きペイロードのベストプラクティス
- 強力な秘密鍵を使用する:ランダムで高エントロピーな秘密鍵を生成し、安全に保管します。
- タイムスタンプを含める:許容範囲外のタイムスタンプを持つリクエストを拒否します。
- 定数時間比較を使用する:
hmac.compare_digestのような関数を使用してタイミング攻撃を防ぎます。 - 秘密鍵を定期的にローテーションする:ローテーション中は複数のアクティブな秘密鍵を許可します。
リトライメカニズム:信頼性の高い配信の確保
署名付きペイロードを使用しても、ネットワーク障害や受信側のエラーによりWebhookの配信が失敗する可能性があります。堅牢なリトライ戦略により、受信側に過負荷をかけることなく、イベントが最終的に配信されることが保証されます。
リトライポリシーの設計
一般的なアプローチは、ジッター付きの指数バックオフです。たとえば、1分後にリトライし、次に5分後、次に30分後と、最大試行回数(例:5回)まで続けます。受信側が重複を排除できるように、ペイロードに一意のイベントIDを含めます。
リトライスケジュールの例:
| 試行 | 遅延 |
|---|---|
| 1 | 即時 |
| 2 | 1分 |
| 3 | 5分 |
| 4 | 30分 |
| 5 | 2時間 |
リトライを使い果たした後は、イベントをデッドレターキューに移動して手動で検査します。
冪等性:重複配信の処理
リトライによって重複配信が発生する可能性があるため、受信側は冪等でなければなりません。ペイロードにイベントIDを含め、受信側が処理済みIDを保存して重複を無視するようにします。あるいは、操作を自然に冪等になるように設計します(例:POSTの代わりにPUTを使用)。
Webhookの実装:ステップバイステップガイド
- イベントとペイロード構造を定義する:システムが発行するイベントと各イベントのJSONスキーマを文書化します。
- 秘密鍵を生成する:Webhookエンドポイントごとに一意の秘密鍵を作成し、安全に共有します。
- 各リクエストに署名する:ペイロードとタイムスタンプに対してHMACを計算し、ヘッダーに含めます。
- バックオフ付きリトライを実装する:キューシステムを使用してリトライをスケジュールします。
- 署名を検証する方法を提供する:受信者向けに検証プロセスを文書化します。
- 監視とログ記録:デバッグのために配信試行と失敗を追跡します。
よくある落とし穴と回避方法
- TLSを無視する:転送中のペイロードを保護するために常にHTTPSを使用します。
- タイムスタンプを検証しない:リプレイ攻撃を許すことになります。
- 無限にリトライする:リソースの枯渇を引き起こす可能性があります。最大値を設定します。
- 即時配信を前提とする:非同期処理を前提に設計します。
FAQ
署名付きWebhookペイロードとは何ですか?
署名付きWebhookペイロードには、受信者が送信者の真正性とデータの完全性を検証できるようにする暗号署名(例:HMAC)が含まれています。
失敗したWebhookを何回リトライすべきですか?
通常、指数バックオフで3〜5回のリトライです。正確な回数はSLAとイベントの重要度によって異なります。
Webhook署名にHMACの代わりにJWTを使用できますか?
はい、JWTも使用できますが、HMACの方がシンプルでWebhook署名には一般的です。JWTはオーバーヘッドが増えるため、認証トークンに適しています。
Webhookペイロードをテストする準備はできましたか?送信前にJSONペイロードを検証して整形するには、JSONフォーマッターをご利用ください。