Webhook解説:署名付きペイロードとリトライ戦略

Backend2026-11-12TryQuickToolBox

イベントを外部サービスに通知するために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分以内)であることを確認します。これによりリプレイ攻撃を防ぎます。

署名付きペイロードのベストプラクティス

リトライメカニズム:信頼性の高い配信の確保

署名付きペイロードを使用しても、ネットワーク障害や受信側のエラーによりWebhookの配信が失敗する可能性があります。堅牢なリトライ戦略により、受信側に過負荷をかけることなく、イベントが最終的に配信されることが保証されます。

リトライポリシーの設計

一般的なアプローチは、ジッター付きの指数バックオフです。たとえば、1分後にリトライし、次に5分後、次に30分後と、最大試行回数(例:5回)まで続けます。受信側が重複を排除できるように、ペイロードに一意のイベントIDを含めます。

リトライスケジュールの例:

試行遅延
1即時
21分
35分
430分
52時間

リトライを使い果たした後は、イベントをデッドレターキューに移動して手動で検査します。

冪等性:重複配信の処理

リトライによって重複配信が発生する可能性があるため、受信側は冪等でなければなりません。ペイロードにイベントIDを含め、受信側が処理済みIDを保存して重複を無視するようにします。あるいは、操作を自然に冪等になるように設計します(例:POSTの代わりにPUTを使用)。

Webhookの実装:ステップバイステップガイド

  1. イベントとペイロード構造を定義する:システムが発行するイベントと各イベントのJSONスキーマを文書化します。
  2. 秘密鍵を生成する:Webhookエンドポイントごとに一意の秘密鍵を作成し、安全に共有します。
  3. 各リクエストに署名する:ペイロードとタイムスタンプに対してHMACを計算し、ヘッダーに含めます。
  4. バックオフ付きリトライを実装する:キューシステムを使用してリトライをスケジュールします。
  5. 署名を検証する方法を提供する:受信者向けに検証プロセスを文書化します。
  6. 監視とログ記録:デバッグのために配信試行と失敗を追跡します。

よくある落とし穴と回避方法

FAQ

署名付きWebhookペイロードとは何ですか?

署名付きWebhookペイロードには、受信者が送信者の真正性とデータの完全性を検証できるようにする暗号署名(例:HMAC)が含まれています。

失敗したWebhookを何回リトライすべきですか?

通常、指数バックオフで3〜5回のリトライです。正確な回数はSLAとイベントの重要度によって異なります。

Webhook署名にHMACの代わりにJWTを使用できますか?

はい、JWTも使用できますが、HMACの方がシンプルでWebhook署名には一般的です。JWTはオーバーヘッドが増えるため、認証トークンに適しています。

Webhookペイロードをテストする準備はできましたか?送信前にJSONペイロードを検証して整形するには、JSONフォーマッターをご利用ください。