Webhook 検証の要件

Webhook を注文確定の根拠にする場合、署名と時刻を必ず検証し、検証済みボディの id で冪等に処理します。実装例を参照してください。

検証	防ぐこと
raw body の HMAC-SHA256	通知の偽造・本文の改ざん
送信時刻の許容ずれ	古い通知のリプレイ
タイミング安全な比較	比較時間を使った情報の推測
ボディの id による重複排除	許容時間内の再送による二重処理

ローテーション中は v1 が複数あるため、すべて集めていずれかと一致するか検証します。ヘッダだけのイベント ID を重複排除の鍵にしないでください。

送信元の制限

本番では固定 IP を予定しています。実際の送信元情報と提供状況を確認して IP 制限を併用します。IP 制限を署名検証の代わりにしないでください。

署名を検証しない構成では、通知本文を注文確定の根拠にできません。その場合の成立確認は加盟店サーバーからのステータス API 照会に限ります。

利用者のパスキー署名やオンチェーンの検証は STBLpay の決済経路の責務であり、加盟店がブラウザで再実装するものではありません。