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

Backend2026-11-01TryQuickToolBox

サードパーティサービスを統合し、そのサービスがあなたのエンドポイントにWebhookを送信するように設定したところです。テストではすべて正常に動作しましたが、本番環境ではイベントの欠落、重複配信、時折発生するセキュリティ上の懸念に気づくでしょう。Webhookは概念としてはシンプルですが、実際には扱いが難しく、特に真正性の検証と障害処理が課題となります。

このガイドでは、署名付きペイロードでWebhookを安全にし、堅牢なリトライメカニズムを実装して信頼性の高い統合を構築する方法を説明します。

Webhookとは？

Webhookはユーザー定義のHTTPコールバックです。ソースシステムでイベント（例：支払いの完了）が発生すると、イベントに関するデータを含むHTTP POSTリクエストを指定したURLに送信します。これにより、ポーリングなしでサービス間のリアルタイム通信が可能になります。

しかし、Webhookには課題があります。リクエストが本当に期待する送信者から来たものかをどうやって確認するのか？エンドポイントが一時的にダウンしていたらどうするのか？そこで署名付きペイロードとリトライの出番です。

署名付きペイロードでWebhookを保護する

署名付きペイロードは、暗号署名を使用してリクエストが送信者から発信され、改ざんされていないことを証明します。一般的なアプローチは、共有シークレットを使用したHMAC（ハッシュベースのメッセージ認証コード）です。

HMAC署名の仕組み

送信者は、秘密鍵を使用してリクエストボディ（および場合によってはタイムスタンプなどのヘッダー）に対してHMACを計算します。署名はヘッダー（例：X-Signature）で送信されます。あなたのサーバーはHMACを再計算し、受信した署名と比較します。一致すれば、リクエストは真正です。

Flaskを使用したPythonの最小限の例を次に示します。

import hmac
import hashlib
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = b'your_shared_secret'

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Signature')
    if not signature:
        abort(400, 'Missing signature')
    body = request.get_data()
    expected = hmac.new(SECRET, body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, signature):
        abort(401, 'Invalid signature')
    # Process the event
    return '', 200

重要なポイント：

タイミング攻撃を防ぐために、常に定数時間比較関数（hmac.compare_digestなど）を使用してください。
リプレイ攻撃を防ぐために、署名対象データにタイムスタンプを含め、数分以上古いリクエストは拒否してください。
シークレットは安全に保管し、クライアント側に決して公開しないでください。

追加のセキュリティ対策

HTTPS：転送中のペイロードを保護するために常にHTTPSを使用してください。
IP許可リスト：プロバイダーがIP範囲を公開している場合は、それらのIPにリクエストを制限してください。
冪等性：リトライにより重複が発生する可能性があるため、イベントIDを使用して重複排除してください。

信頼性の高いリトライの実装

Webhookのコンシューマーは失敗する可能性があります。サーバーがダウンしているか、処理がタイムアウトするかもしれません。送信者は指数バックオフで失敗した配信をリトライする必要があります。コンシューマーとして、リトライを優雅に処理する必要があります。

送信者側（Webhookシステムを構築する場合）

迅速に2xxを返す：タイムアウトを避けるために、処理前に受信を確認します。非同期処理にはキューを使用します。
失敗時にリトライ：タイムアウト（例：5秒）内に2xxを受信しない場合、遅延を増やしてリトライします（例：1秒、5秒、30秒、5分、30分）。
リトライ回数を制限：最大試行回数（例：5回）後、配信を失敗としてマークし、アラートを出します。
一意のイベントIDを含める：コンシューマーが重複排除できるようにします。

コンシューマー側（あなたのエンドポイント）

迅速に応答：すぐに2xxを返し、必要に応じて非同期で処理します。
冪等性を保つ：イベントIDを使用して同じイベントを二重に処理しないようにします。
重複を処理：処理済みイベントIDを妥当な期間保存します。
失敗をログに記録：処理が失敗した場合、5xxを返してリトライをトリガーしますが、無限ループに陥らないように注意してください。

比較：署名付きペイロード vs 基本認証

アプローチ	セキュリティ	複雑さ	リプレイ保護
HMAC署名	高（完全性 + 真正性）	中程度	あり（タイムスタンプ使用時）
基本認証	低（ヘッダーに認証情報）	低	なし
IP許可リスト	中（ネットワークレベル）	低	なし

ローカルでのWebhookテスト

開発中は、Webhookを受信するための公開URLが必要です。ngrokやlocaltunnelなどのツールでローカルサーバーを公開できます。署名検証とリトライ動作を、シミュレートした失敗で常にテストしてください。

Webhookペイロードを検査する際、読みやすくするためにJSONを整形する必要があるかもしれません。JSON Formatterは、JSONボディを整形して検証するのに役立ちます。

FAQ

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

署名付きペイロードには暗号署名（多くの場合HMAC）が含まれ、受信者がリクエストの真正性と完全性を検証できるようにします。

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

固定の回数はありません。一般的な慣行では、指数バックオフで3〜10回のリトライが行われます。重要なのは、信頼性とリソース使用量のバランスを取り、永続的な失敗に対してアラートを出すことです。

署名なしでWebhookを使用できますか？

推奨されません。署名がないと送信者を検証できず、エンドポイントがなりすましに対して脆弱になります。本番環境では常に署名を使用してください。

Webhookペイロードのデバッグを始めませんか？JSON Formatterを試して、JSONデータを迅速に検証および整形してください。