Webhook 署名の検証と冪等性

このページは次のページに続きます Agent Java SDK WEBHOOKS.md コミット fa6c7b6 で。これはドキュメントのみの更新です。警告ヘルパー メソッドを含む新しい SDK アーティファクトはリリースされませんでした。

4 つのイベント タイプはすべて 1 つのマーチャント コールバック URL を使用し、本体 event によってディスパッチされます。見る Webhook イベントと清算に関する警告 イベントフィールドとペイロードの例については、

Webhook ヘッダー

timestamp + nonce + rawBody

イベントのべき等性

ビジネス処理を使用して、販売者および environment スコープ内で重複排除をアトミックに継続します。異なる notificationId 値は、独立した FIRST / UPGRADE / REMINDER 通知を識別します。ユーザー、エピソード、または eventType でグループ化して通知を破棄しないでください。空の冪等キーは重複排除には使用できません。 SDK はヘルパー キーのみを返します。ビジネス データを保持したり処理したりしません。異なる本体を持つ同じアイデンティティを競合として記録します。処理された本文を上書きしないでください。

署名の検証と受信

マーチャント API シークレットを使用して、timestamp + nonce + rawBody の HMAC-SHA256 16 進署名を計算します。元の受信バイトを確認します。最初に JSON の書式設定、フィールド名の変更、本文の再シリアル化を行わないでください。

最初に署名を検証し、次に時間枠 (±300 秒を推奨)、販売者、および環境を確認します。次に、冪等性 ID を抽出し、通知を確実に処理します。診断のために未知のイベント値を保存します。決してそれらを資金調達の成功として解釈しないでください。検証ヘルパーは、時間枠、所有権、または永続的な重複排除チェックを実行しません。

処理が完了した後、または同一の重複を確認した後、HTTP 2xx を返します。失敗した場合は 2xx 以外を返します。警告送信者には 5 秒の HTTP タイムアウトと最大 8 回の試行があります。再試行では、凍結されたボディが保持されます。署名のタイムスタンプとナンスのみが変更されます。確実に受け入れられた後、速やかに対応します。長時間にわたるビジネス作業では、マーチャント独自の永続タスクを使用できます。

販売者からの通知は、ユーザーのオンライン ステータスには依存しません。プラットフォーム ユーザーのプッシュはオンラインでのベストエフォート配信のみであり、オフラインでの再生はありません。フェーズ 1 には通知受信箱がありません。

成功した応答と再試行の停止

ファンドのコールバックと清算警告では、HTTP ステータス コードのみを使用して配信の成功を判断します。送信者は応答本文 code、success、result、または message を解釈せず、固定の OK / success 応答を必要としません。

応答本文は空、テキスト、または JSON の場合があります。例の result フィールドは販売者向けの情報であり、プロトコル要件ではありません。 202 Accepted はプラットフォームの再試行も停止するため、単にメモリ内の非同期タスクを開始するのではなく、マーチャントの永続タスク キューに通知を確実に保存した後にのみ通知を返します。

成功した対応例

ビジネス処理が完了した後、または通知がマーチャント自身の保留キューに確実に保存された後、次のようになります。

HTTP/1.1 200 OK
Content-Type: application/json
{"result":"RECEIVED"}

レスポンスボディが必要ない場合:

HTTP/1.1 204 No Content

同一の本文を持つ処理済みの通知の場合、重複するビジネス処理をスキップし、引き続き 2xx を返します。

HTTP/1.1 200 OK
Content-Type: application/json
{"result":"DUPLICATE"}

障害対応例

データベースが一時的に利用できず、販売者が処理を完了していない、または通知を確実に保存していない場合は、プラットフォームが再試行できるように、非 2xx を返します。

HTTP/1.1 503 Service Unavailable
Content-Type: application/json
{"result":"FAILED","message":"temporary storage failure"}

ビジネス データや成功した重複排除レコードを更新せずに、無効な署名を拒否します。

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{"result":"INVALID_SIGNATURE"}

これらの応答本文は、再試行の決定を変更しません。 401 または 409 によって再試行が永久に停止されるとは期待しないでください。署名、通知内容、または販売者の設定を調査します。

間違った例: 次の応答は、引き続き正常な配信としてカウントされます。 success:false のため、プラットフォームは再試行しません。

HTTP/1.1 200 OK
Content-Type: application/json
{"success":false,"code":500,"message":"processing failed"}

フレームワークまたはグローバル例外ハンドラーがビジネス障害を HTTP 200 でラップする場合は、コールバック エンドポイントで正しい障害ステータスを明示的に設定します。

信頼性の高い確認応答と二重配信

推奨される順序: 署名を検証し、時刻/マーチャント/環境を確認する → 冪等性 ID を抽出する → トランザクション内のビジネス データと成功した重複排除レコードを処理する、または保留中のタスクを確実に保存する → コミットが成功した後に 200/204 を返す。データベースへの書き込みが成功する前に、2xx を返したり、通知を処理済みとしてマークしたりしないでください。

販売者の処理が成功した後でも、重複配信が発生する可能性があります。応答が失われたり、プラットフォームが 2xx を受信して​​も永続化に失敗したりする可能性があります SUCCESS。 HTTP コールバックは 1 回限りの配信を保証するものではありません。マーチャントおよび environment スコープ内で重複排除を維持します。資金は orderType:orderId:targetStatus を使用します。警告には liquidation.warning:notificationId を使用します。同一の処理済みボディの場合は、資金を入金したり再度リマインダーを発行したりせずに 2xx を返します。ボディが異なる同じ ID の場合は、競合を記録し、2xx 以外を返します。元のレコードを上書きしないでください。

承認の成功は、資金操作が成功したことを意味するのではなく、販売者が通知を受信/処理したことを意味します。 targetStatus=FAILED で有効な資金通知を記録した後、2xx も返します。注文の失敗は、通知の確認を拒否する理由にはなりません。

資金と環境の境界線

元の契約転送 webhook および queryOrder フローは、資金調達に自動的には適用されません。 queryWalletTransfer と元の注文環境を使用して資金調達操作を確認します。資金には status が使用されます。元の契約転送応答では orderStatus を使用します。成功した HTTP 応答または code=0 自体は、資金が移動したことを証明するものではありません。

明示的にシミュレートされた契約転送通知には environment=SIMULATED が含まれます。最初に生の本文を確認し、次にユーザー、金額、注文 ID、および環境を保存されたローカル ビジネス注文と比較して確認します。

資金回収ガイド · 環境ガイド