Webhook解説:署名付きペイロードと信頼性の高い統合のためのリトライ

Backend2026-11-13TryQuickToolBox

決済プロバイダーからWebhookを受信するエンドポイントを構築したばかりだとします。最初のテストは問題なく動作しますが、本番環境ではイベントの欠落、二重請求、リクエストが本物かどうかを判断する方法がないことに気づきます。Webhookは概念としてはシンプルですが、正しく実装するのは難しいです。このガイドでは、署名付きペイロードでWebhookを保護し、堅牢なリトライロジックを実装して統合がサイレントに壊れないようにする方法を説明します。

Webhookとは何か、なぜ重要なのか

Webhookはイベントによってトリガーされるユーザー定義のHTTPコールバックです。アプリケーションがAPIをポーリングして変更を確認する代わりに、何かが起こったときにサービスがデータをエンドポイントにプッシュします。これにより統合が効率的になり、ほぼリアルタイムになります。

一般的なユースケースには、決済通知(例:Stripe)、CI/CDトリガー(例:GitHub)、メッセージングプラットフォーム(例:Slack)などがあります。しかし、このプッシュモデルでは、リクエストがいつ到着するかを制御できません。そのため、セキュリティと信頼性を明示的に処理する必要があります。

セキュリティの問題:署名なしのWebhookは危険

署名なしのWebhookは、公開URLへの単なるHTTP POSTです。誰でも決済プロバイダーから来たように見えるリクエストを送信できます。検証がなければ、攻撃者はイベントを偽造し、不正注文、データ漏洩、または不正な操作を引き起こす可能性があります。

解決策はペイロードに署名することです。送信者は共有シークレットを使用してリクエストボディの暗号署名を計算し、ヘッダーに含めます。エンドポイントは署名を再計算して比較します。一致すれば、リクエストが本物であり、改ざんされていないことがわかります。

HMACでWebhookペイロードに署名する方法

HMAC(Hash-based Message Authentication Code)はWebhook署名の標準です。秘密鍵とハッシュ関数(SHA-256など)を使用して、ペイロードとシークレットに固有の署名を生成します。

送信者がPythonでペイロードに署名する例:

import hmac
import hashlib
import json

secret = b'your_shared_secret'
payload = json.dumps({'event': 'payment.success', 'amount': 1000}).encode('utf-8')
signature = hmac.new(secret, payload, hashlib.sha256).hexdigest()
# ヘッダーに署名を含める: X-Signature: 

受信側では、ペイロードを処理する前に署名を検証する必要があります:

import hmac
import hashlib

def verify_signature(payload, received_signature, secret):
    expected = hmac.new(secret, payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received_signature)

重要:タイミング攻撃を防ぐために、常にhmac.compare_digestのような定数時間比較関数を使用してください。また、JSONシリアライズが異なる可能性があるため、解析済みバージョンではなく生のリクエストボディに対して署名を検証してください。

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

障害の処理:リトライと冪等性

Webhookは失敗する可能性があります:サーバーがダウンしている、ネットワークが切断される、エンドポイントがエラーを返すなどです。信頼性の高い送信者は配信をリトライしますが、受信側は重複や順序外のイベントを処理できるように設計する必要があります。

リトライ戦略

ほとんどのWebhookプロバイダーは、ジッター付きの指数バックオフを使用しています。たとえば、1分後にリトライ、次に5分後、次に30分後、最大試行回数まで続けます。これにより、システムに過負荷をかけずに回復する時間を与えます。

送信側を構築する場合は、スケジュールされたリトライを備えたキューを実装します。ペイロードと試行回数を保存し、ワーカーを使用してリトライを処理します。

冪等性:安全なリトライの鍵

リトライは重複配信を引き起こす可能性があるため、エンドポイントは冪等でなければなりません。つまり、同じイベントを複数回処理しても、1回処理した場合と同じ効果が得られる必要があります。

一般的なアプローチ:

Pythonでの簡単な冪等性チェックの例:

def process_event(event_id, payload):
    if db.exists('processed_events', event_id):
        return  # すでに処理済み
    # ペイロードを処理
    db.insert('processed_events', event_id)

競合状態を避けるために、チェックと処理が単一のトランザクションで行われるようにしてください。

比較:ポーリング vs. Webhook

側面ポーリングWebhook
レイテンシ間隔に依存(例:5分)ほぼリアルタイム
サーバー負荷変更がなくても常にリクエストイベント時のみリクエスト
複雑さ実装が簡単署名、リトライ、冪等性が必要
信頼性リトライを自分で制御送信者のリトライポリシーに依存

ステップバイステップ:安全なWebhookレシーバーの実装

  1. HTTPSエンドポイントを設定する:POSTリクエストを受け入れ、生のボディを読み取ります。
  2. 署名ヘッダーを抽出する(例:X-Signature)と、存在する場合はタイムスタンプヘッダーも抽出します。
  3. HMACとシークレットを使用して署名を検証する。無効な場合は拒否します。
  4. タイムスタンプを確認する:リプレイ攻撃を防ぐため(例:5分以上古い場合は拒否)。
  5. ペイロードを解析する:イベントIDを抽出します。
  6. 冪等性を確認する:データベースでイベントIDを検索します。
  7. イベントを処理する:イベントIDも記録するトランザクション内で行います。
  8. 2xxステータスを迅速に返す:受信を確認します。処理に時間がかかる場合は、ジョブをキューに入れて202 Acceptedを返します。

Webhook実装のテスト

ngrokなどのツールを使用してローカルサーバーを公開し、Webhookをシミュレートします。署名検証、冪等性、リトライロジックの単体テストを作成します。たとえば、重複するイベントIDが無視されること、無効な署名が401を返すことをテストします。

デバッグ時には、受信したペイロードと署名をログに記録します(ただし、シークレットは決してログに記録しないでください)。JSONペイロードを扱う場合、JSONフォーマッターを使用すると、構造をすばやく検査および検証できます。

FAQ

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

署名付きペイロードには、共有シークレットを使用してリクエストボディに対して計算された暗号署名(通常はHMAC)が含まれます。受信者は署名を検証して、リクエストが本物であり、変更されていないことを確認します。

Webhookは何回リトライすべきですか?

普遍的な数はありませんが、一般的な慣行は指数バックオフで3〜5回のリトライです。その後、イベントは失敗としてマークされ、手動介入またはデッドレターキューが必要になることがよくあります。

HTTPSなしでWebhookを使用できますか?

プレーンHTTPでWebhookを使用すべきではありません。TLSがないと、攻撃者がペイロードと署名を傍受し、リクエストをリプレイまたは変更する可能性があります。常にHTTPSを使用してください。

Webhookペイロードを検査およびフォーマットする準備はできましたか?無料のJSONフォーマッターを試して、JSONデータを即座に検証および整形してください。