生產準備

Webhook 簽名驗證與冪等性

6MM agent webhook 與原始請求體驗證，並處理重試、逾時及重複事件，避免重複業務操作。

以 Markdown 格式查看

Webhook 會通知合作夥伴後端非同步的業務狀態變更。由於傳送可能會被重試，每個接收端必須在解析受信任資料前驗證簽名，且事件必須冪等處理。

Webhook 標頭

標頭描述
X-代理時間戳Unix 的時間戳記在幾秒內。
X-特工-假人重播保護 nonce。
X-代理-簽名HMAC-SHA256 簽名。
timestamp + nonce + rawBody

在重建有符號值時，請使用截 HTTP 收到的原始請求實體。先解析並重新序列化 JSON 可以改變空白或欄位順序，產生不同的簽章。

驗證流程

  1. 讀取時間戳、nonce 和簽章標頭。
  2. 擷取未修改的原始請求實體。
  3. 建造 timestamp + nonce + rawBody。
  4. 計算HMAC- 與夥伴API 秘密SHA256。
  5. 使用恆定時間比較，比較計算出的與收到的簽名。
  6. 套用核准的時間戳新鮮度及非重複使用檢查。
  7. 只有在驗證成功後才解析並處理事件。

當官方 Agent SDK 驗證器可用時，請使用它，而非維護獨立的簽署碼。

訂單冪等性

案件操控
初始轉移申請創造一個全球獨一無二的 agentOrderNo。
HTTP 暫停在建立新 agentOrderNo 之前，先查詢原始。
PROCESSING 回應等待 webhook 或查詢訂單狀態。
重複的Webhook依冪等性鍵與最終狀態進行重複解碼。

儲存足夠資訊以辨識重複送達並安全恢復：

場地目的
活動或商業鑰匙唯一識別通知或操作。
合作夥伴訂單號碼將事件與原始請求連結起來。
有效載荷雜湊有助於辨識重複的重複有效載荷衝突。
目前處理狀態有被接受、處理、成功與失敗的工作。
最終業務狀況防止終端動作重複應用。
處理過的時間戳記支援調查與保留政策。

盡可能在同一筆交易中提交業務變更與冪等性記錄。重複事件應回傳已知結果，而非重複套用餘額、訂單或使用者變更。

暫停與重試規則

HTTP逾時並不證明原始請求失敗。使用原始agentOrderNo查詢操作，或等待其 webhook 後，再決定是否需要其他行動。每次逾時後建立新的業務訂單號碼可能導致重複資金流動。

製作檢查清單

  • 在 JSON 解析或業務處理前驗證簽名。
  • 獨立於解析後的有效載荷保存原始本體。
  • 依核准的整合政策拒絕過時或重播請求。
  • 使事件處理安全，適合重複且順序錯序的傳遞。
  • 記錄事件 ID、合作夥伴訂單號碼、處理結果及請求時間。
  • 從日誌和支援附件中刪除秘密與簽章值。
秘密與 HMAC 簽名

保護用於請求與 webhook 驗證的 API 秘密。

Agent SDK 概述

檢視完整的後端整合工作流程。

SDK 故障排除

調查被拒絕的簽名、重複事件及待執行的行動。