> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.6mm.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.6mm.com/_mcp/server.

# Webhook 簽名驗證與冪等性

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

<h2 id="webhook-headers">
  Webhook 標頭
</h2>

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

```text
timestamp + nonce + rawBody
```

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

<h2 id="verification-flow">
  驗證流程
</h2>

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

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

<h2 id="order-idempotency">
  訂單冪等性
</h2>

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

<h2 id="recommended-idempotency-record">
  推薦的冪등 性紀錄
</h2>

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

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

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

<h2 id="timeout-and-retry-rule">
  暫停與重試規則
</h2>

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

<h2 id="production-checklist">
  製作檢查清單
</h2>

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

<h2 id="related-docs">
  相關文件
</h2>

#### [秘密與 HMAC 簽名](/zh-TW/sdk/security/secrets-signing)

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

#### [Agent SDK 概述](/zh-TW/sdk/agent-sdk/overview)

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

#### [SDK 故障排除](/zh-TW/sdk/security/troubleshooting)

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