ウェブフック署名検証と冪等性

Webhookは非同期のビジネス状態変更をパートナーのバックエンドに通知します。配信が再試される可能性があるため、すべての受信者は信頼されたデータを解析する前に署名を検証し、イベントを冪等的に処理しなければなりません。

ウェブフックヘッダー

timestamp + nonce + rawBody

署名値を再構築する際は、 HTTP 上で受信した正確な生のリクエストボディを使用します。まず解析して再シリアライズ JSON 、空白やフィールドの順序を変え、異なる署名を生成できます。

検証フロー

1. タイムスタンプ、ノンス、署名ヘッダーを読み取る。
2. 修正されていない生のリクエストボディを取得する。
3. timestamp + nonce + rawBodyを築く。
4. パートナーとの秘密HMACSHA256計算API。
5. 計算された署名と受信された署名を定時比較を用いて比較する。
6. 承認されたタイムスタンプの新鮮さおよびノンス再利用チェックを適用します。
7. 検証が成功した後にのみイベントを解析・処理する。

公式の Agent SDK 検証器が利用可能になった場合は、独立した署名コードを維持する代わりにそれを使いましょう。

位数冪起等

推奨冪等性記録

繰り返し配達を認識し安全に回復できる十分な情報を保存する:

可能な限り、ビジネス変更と冪등 記録を同じトランザクションにコミットしてください。繰り返しイベントを行うと、残高、注文、ユーザーの変更を再度適用する代わりに既知の結果を返すべきです。

タイムアウトと再挑戦ルール

HTTPタイムアウトは元のリクエストが失敗したことを証明しません。元のagentOrderNoを使って操作を照会するか、ウェブフックを待ってから次の処理が必要かどうか判断してください。タイムアウト後に新しい受注番号を作成すると、重複した資金移動を引き起こす可能性があります。

生産チェックリスト

• 解析やビジネス処理 JSON 署名を確認する。
• 解析されたペイロードとは独立して生のボディを保存する。
• 承認された統合ポリシーに従って、古いリクエストや再再生リクエストを拒否する。
• イベント処理を繰り返しかつ順序外の配信に安全にすること。
• イベントID、パートナー注文番号、処理結果、リクエスト時間を記録する。
• ログやサポート添付ファイルから秘密情報や署名値を黒塗りすること。

関連文書