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

Backend2026-11-14TryQuickToolBox

APIを構築し、イベントが発生したときに他のサービスへ通知する必要が出てきました。ポーリングは非効率なので、Webhookを実装します。しかしすぐに気づくでしょう:ペイロードが本物であることをどう保証するのか?受信側がダウンしていたらどうするのか?適切な対策がなければ、Webhookはセキュリティホールや信頼性の悪夢になり得ます。

この記事では、Webhookの基本を解説し、特に2つの重要な側面に焦点を当てます:セキュリティのための署名付きペイロードと、信頼性のためのリトライメカニズムです。堅牢なWebhookシステムを構築するための実践的なコード例とベストプラクティスを提供します。

Webhookとは何か?

Webhookはユーザー定義のHTTPコールバックです。特定のイベントが発生したときに、あるシステムが別のシステムへリアルタイムにデータを送信できるようにします。データを取得するAPIとは異なり、Webhookはデータをプッシュします。このため、イベント駆動型アーキテクチャに最適です。

一般的なユースケースには、決済通知(例:Stripe)、CI/CDトリガー(例:GitHub)、メッセージングプラットフォーム(例:Slack)などがあります。送信側は、受信側が提供するURLへHTTP POSTリクエストを送り、イベントの詳細を含むペイロードを渡します。

なぜ署名付きペイロードでWebhookを保護するのか?

Webhookのエンドポイントは公開されているため、なりすましに対して脆弱です。攻撃者が偽のペイロードを送り、意図しないアクションを引き起こす可能性があります。これを防ぐため、送信側は共有シークレットを使ってペイロードに署名します。受信側は署名を検証し、真正性と完全性を確認します。

署名は通常、秘密鍵を使ってペイロードのHMAC(Hash-based Message Authentication Code)を生成することを伴います。署名はヘッダー(例:X-Signature)で送信されます。受信側はHMACを再計算し、受信した署名と比較します。

署名付きペイロードの実装方法

Flaskを使ったPythonの簡単な例を見てみましょう。送信側は署名を計算します:

import hmac
import hashlib
import json
import requests

secret = b'your_shared_secret'
payload = {'event': 'payment.success', 'amount': 100}
body = json.dumps(payload).encode('utf-8')
signature = hmac.new(secret, body, hashlib.sha256).hexdigest()

headers = {'Content-Type': 'application/json', 'X-Signature': signature}
requests.post('https://receiver.com/webhook', data=body, headers=headers)

受信側は署名を検証します:

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

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

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

ベストプラクティス:

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

Webhookの配信は、ネットワークの問題、受信側のダウンタイム、処理エラーによって失敗する可能性があります。堅牢なシステムは、指数バックオフを伴って失敗した配信をリトライすべきです。

リトライ戦略

一般的なアプローチ:遅延を増やしながら最大N回リトライします(例:1秒、5秒、30秒、5分、30分)。リトライを使い果たしたら、配信を失敗としてマークし、アラートを出します。

以下は、requestsライブラリとtenacityを使ったPythonの簡単なリトライメカニズムです:

from tenacity import retry, stop_after_attempt, wait_exponential
import requests

@retry(stop=stop_after_attempt(5), wait=wait_exponential(multiplier=1, min=1, max=60))
def send_webhook(url, payload, signature):
    headers = {'X-Signature': signature}
    response = requests.post(url, json=payload, headers=headers, timeout=10)
    response.raise_for_status()
    return response

リトライのベストプラクティス:

比較:署名付きペイロード vs ベーシック認証

アプローチセキュリティ複雑さリプレイ保護
ベーシック認証低(毎回認証情報を送信)低なし
署名付きペイロード(HMAC)高中あり(タイムスタンプ併用時)

ステップバイステップ:リトライ付きWebhook送信側の構築

  1. イベントペイロードを定義し、一意のイベントIDとタイムスタンプを含める。
  2. 署名を計算する。生のボディに対してHMAC-SHA256を使用する。
  3. リクエストを送信する。署名はヘッダーに含める。
  4. 失敗を処理する。指数バックオフでリトライする。
  5. 配信をログに記録し、可視性を提供する。

Webhookのテスト

ngrokなどのツールを使ってローカルサーバーを公開し、Webhook配信をテストします。問題を早期に発見するため、テストでは必ず署名を検証してください。

FAQ

Webhookにおける署名付きペイロードとは?

署名付きペイロードとは、送信側が共有シークレットで生成した暗号署名(通常はHMAC)を含めるWebhookリクエストです。受信側は署名を検証し、リクエストが真正であり改ざんされていないことを確認します。

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

決まった回数はありませんが、一般的な慣行は指数バックオフを伴う3〜5回のリトライです。受信側の典型的なダウンタイムとイベントの重要度を考慮してください。常に手動リトライを許可しましょう。

Webhookの署名にJWTを使えますか?

はい、JWTも使えますが、より複雑です。HMAC署名はよりシンプルで、ほとんどのケースで十分です。クレームを含める必要がある場合は、JWTが適しているかもしれません。

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