BuildShelf運営者による記事です。末尾に自社の有料ソースコード商品への短い案内があります。以下の検証例はMITライセンスの無料サンプルとして動かせます。
Webhook受信の実装で、署名検証、鮮度確認、重複処理を一つの「セキュリティ確認」として扱うと穴が残ります。署名は本文の真正性、Stripeの署名付き時刻は許容時間内の配信か、重複キーは同じイベントを再び扱うかという別々の問いに答えます。
1. JSONへ変換する前の bytes を使う
送り手が署名したのはHTTP本文のバイト列です。JSONを一度オブジェクトにして再シリアライズすると、空白やキー順が変わり、同じ意味のデータでもHMACが一致しません。受信ハンドラーは生の本文を保全し、ヘッダーとともに検証関数へ渡してから解析します。本文サイズの上限も先に確認します。
GitHubのX-Hub-Signature-256は、sha256=の後にSHA-256 HMACの16進表現が続く形です。サンプルでは次の比較を行います。
expected = hmac.new(secret.encode(), raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, header[7:]):
raise ValueError("bad signature")
ヘッダー形式とX-GitHub-Deliveryの長さも検査します。秘密鍵の保管・ローテーションや実環境のHTTPフレームワークへの接続は利用側で設計してください。
2. Stripeは署名付き時刻も検査する
StripeのStripe-Signatureにはtとv1の値が含まれます。署名対象は時刻文字列、ドット、そして生の本文です。
signed = timestamp.encode() + b"." + raw
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
サンプルは時刻差が300秒を超える場合に拒否し、複数v1候補を上限付きで受け付けます。tが重複するなど解釈が曖昧なヘッダーも拒否します。署名検証後にJSONからイベントIDを読みます。実際の時刻はサーバー時計を使い、時計同期とプロバイダー仕様を運用時に確認します。
対してGitHubの署名には署名付き時刻がありません。正しい署名を検証できても、初めて見る配信が新しいとは断定できません。初回受信の鮮度を保証したと宣伝しないことが重要です。
3. 重複配信は処理結果と結びつける
公開サンプルのclassify_onceはPythonのsetを使い、同一プロセス内でfirstとduplicateを返すだけです。再起動で消え、複数ワーカー間で共有されません。処理に失敗したイベントまで「受信済み」として固定すると、配信を失う危険があります。
本番では、プロバイダーとイベントIDを組み合わせたキーなどを永続ストアの一意制約で扱い、受信した状態と業務処理が完了した状態を区別します。外部副作用の完全な一回性まではローカルのフラグだけで保証できません。
実際に試す
python3 webhook_signature/demo.py
python3 -m unittest discover -s tests -v
合成本文と合成秘密鍵による実測出力です。
stripe: first, duplicate
github: first, duplicate
テストには本文改変、古いStripe時刻、重複t、不正なGitHub配信ID、プロセス内重複などを含みます。この出力は耐障害性や永続的なリプレイ防御の証明ではありません。実際のStripe/GitHub配信を使う際は両社のStripe署名検証資料とGitHub署名検証資料も参照してください。
無料の実装・テスト:BuildShelf public examples。
運営者による製品案内: 永続的なSQLite受信重複判定まで必要ならWebhook Signature Mini、キュー・再試行・DLQ・管理者再実行まで必要ならWebhook Reliability本版の範囲を比較できます。いずれもCLI/ソースコード商品で、ホスト型GUIではありません。