--- title: "在 Webhook 端點接收 Tokenz 事件" description: "透過 Webhook 接收 Tokenz 帳戶中的事件,讓您的系統自動執行後續處理。" source: "https://docs.tokenz.one/zh-TW/v3/checkout/webhooks" api_version: "v3" locale: "zh-TW" version_status: "current" docs_stage: "prod" --- # 在 Webhook 端點接收 Tokenz 事件 透過 Webhook 接收 Tokenz 帳戶中的事件,讓您的系統自動執行後續處理。 **金額格式:** Webhook 酬載中的所有貨幣值(如 `amount` 欄位)均以各貨幣的最小單位表示。請參閱[支援的貨幣](https://docs.tokenz.one/zh-TW/v3/checkout/currency)以了解每種貨幣的確切編碼。 ## 為何使用 Webhook 串接 Tokenz Checkout 時,應用程式需要接收帳戶中的事件,再由後端執行相應操作。 先註冊 Webhook 端點。之後帳戶中發生事件時,Tokenz 會透過 HTTPS,以 JSON 格式將事件資料傳送到您的應用程式。 除了處理結帳完成後的重新導向,也建議串接 Webhook,以接收付款結果通知。 ## 事件概述 Tokenz 會透過事件通知您帳戶中的活動。 事件發生時,Tokenz 會建立新的事件物件。一次 API 請求可能產生多個事件。 註冊 Webhook 端點後,Tokenz 會透過 POST 請求將事件物件傳送到該端點。應用程式收到事件後即可執行後續處理,例如收到 `order.succeeded` 後發放遊戲物品。 ### 事件物件 傳送到 Webhook 端點的事件物件包含相關物件的快照,以及事件的中繼資料。 查看我們發送到您 webhook 的事件類型完整列表。 ### 事件酬載(payload)範例 以下範例是訂單付款成功後傳送的事件。 ```json { "id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6", "object": "order.succeeded", "createdAt": "2025-09-24T03:22:20.297Z", "test": true, "eventData": { "type": "order", "version": "v3", "data": { "order": { "id": "order_1D5xA9BnKfv_t", "object": "order", "status": "succeeded", "amount": { "amount": 3700, "currency": "JPY" }, "items": [ { "id": "item_1D6F8mR5TnK_t", "detail": { "product": { "price": { "amount": 1200, "currency": "JPY" }, "quantity": 3, "label": "ひとにぎりのエメラルド", "description": "80+8", "images": [ "https://images.ctfassets.net/z82qbo7cv7ia/1dWPbk5Qx2M1Qikj6Knyuc/e37b2c26829c0d30793a348ae3adb3b0/fake-pass.webp" ] } } }, { "id": "item_1xejV7puGeK_t", "detail": { "product": { "price": { "amount": 100, "currency": "JPY" }, "quantity": 1, "label": "Diamond", "description": "", "images": [], "sku": "sku_103843dfjhdfgiu", "taxCategory": "VIRTUAL_CURRENCY" } } } ], "description": "Game items purchase", "externalOrderId": "ORDER_2024_001", "recipientId": "user_42931", "metadata": { "cartId": "cart_8812" }, "test": true, "expiresAt": "2024-12-31T23:59:59Z", "createdAt": "2024-01-15T10:00:00Z", "updatedAt": "2024-01-15T10:05:30Z" } } } } ``` ### 正式模式和測試模式 您可能會接收到來自正式模式和測試模式的事件傳送請求,這取決於您是否使用單個端點來處理這兩種模式。請用測試旗標判斷物件屬於哪個模式,並採取對應的處理方式。 ### 版本 `version` 表示 API 版本,決定 `eventData.data` 中實體的結構,例如上方範例中的 `eventData.data.order`。 ### 事件的種類 | 種類 | 說明 | | --- | --- | | `order.created` | 當有一個新的 order 物件透過 [Create a Checkout Session](https://docs.tokenz.one/zh-TW/v3/api/main) API 建立時。 | | `order.succeeded` | 消費者完成訂單付款後,即可向客戶提供商品。 | | `order.expired` | 當訂單已過期時。 | | `order.canceled` | 當訂單已被取消時。 | | `order.failed` | 當訂單付款失敗時。 | | `refund.created` | 退款申請建立時。 | | `refund.failed` | 當退款失敗時。 | | `dispute.created` | 當爭議已建立時。 | | `dispute.closed` | 當爭議已結案時。 | | `redemption.completed` | 禮品碼兌換或免費道具領取完成。使用 `kind` 區分流程(`source` 已棄用);免費道具領取不包含 `code`。 | `user.validation` 不在此清單中:它是由您的端點回應的請求,而不是事件。請參閱[接收者 ID 驗證](https://docs.tokenz.one/zh-TW/v3/checkout/webhooks#player-id-checks)。 ## 接收者 ID 驗證 玩家在您的 Tokenz 商城中輸入接收者 ID 後,商城會在玩家購買或領取免費物品之前驗證該 ID。每次驗證時,Tokenz 都會傳送 `user.validation` 請求,詢問您的伺服器該接收者 ID 對應的帳號是否存在;如果可以重複使用先前的答覆,則不會傳送(請參閱[回應的重複使用](https://docs.tokenz.one/zh-TW/v3/checkout/webhooks#player-id-check-reuse))。Tokenz 從回應中讀取您的答覆,最多等待 3 秒,而且從不重試。建立 Checkout Session 不會傳送它,無論是透過 API 還是從商城建立。 完整的請求與回應結構請參閱 [User validation API 參考](https://docs.tokenz.one/zh-TW/v3/api/user-validation)。 ### 設定驗證 URL - 在 **設定** > **開發者** > **使用者驗證** 中設定 URL。測試和正式各有自己的 URL 和簽章金鑰,請先把主控台切換到要設定的模式。簽章金鑰只會在產生時顯示一次。 - Tokenz 只會把 `user.validation` 傳送到這個 URL。Webhook 端點不會收到它,即使是接收所有事件的端點。 - 要檢查您的伺服器,請輸入遊戲中的接收者 ID 並選擇 **傳送測試驗證**。主控台會顯示伺服器的回覆。Tokenz 不會保存任何內容。 - 設定正式驗證 URL 之前,您的商城無法在正式環境中啟用。 正式商城中的購買由您的正式 URL 驗證,`test` 為 `false`。測試預覽中的購買由您的測試 URL 驗證,`test` 為 `true`。如果沒有設定測試 URL,測試預覽會不經驗證直接接受輸入的 ID。 ### 請求 Tokenz 傳送一個帶 JSON 內文的 `POST`: ```json { "id": "9f8d3c2b-1a4e-4f6d-8b0c-2e5a7d9f1c34", "object": "user.validation", "createdAt": "2026-07-22T09:15:00Z", "test": false, "credentials": { "type": "recipientId", "recipientId": "player-42931" } } ``` - 每次驗證的 `id` 都不同。用它來對照您和我們的日誌,不要把它當作冪等鍵。 - 傳送到測試 URL 的驗證中 `test` 為 `true`。此時請用您的測試玩家核對 ID。 - `credentials.type` 為 `recipientId`,目前只有這一種類型。`credentials.recipientId` 是玩家輸入的接收者 ID。 請求帶有與事件投遞相同的 `Tokenz-Signature` 標頭,由驗證 URL 的簽章金鑰產生,而不是 webhook 端點的簽章金鑰。回應前請以原始請求內文驗證它。請參閱[保護您的 Webhook 端點](https://docs.tokenz.one/zh-TW/v3/checkout/webhooks-get-started#3.-%E4%BF%9D%E8%AD%B7%E4%BD%A0%E7%9A%84-webhook-%E7%AB%AF%E9%BB%9E)。 ### 您的回應 以 HTTP `200` 回應,並說明玩家是否存在: ```json { "valid": true } ``` ```json { "valid": false } ``` - 無論玩家是否存在,都回傳 `200`。Tokenz 會把 2xx 以外的狀態碼(包括重新導向)或不含 `valid` 的內文視為服務故障,而不是未知玩家。 - 在 3 秒內回應。如果 Tokenz 未能及時取得判定,玩家將無法付款,並會被提示再試一次。下文的重試與冪等性僅適用於事件。 - 只回傳 `valid` 和選填的 `validUntil`,不要包含玩家詳情。玩家可以得知驗證是否通過,但 Tokenz 不會將伺服器的原始回應轉送給玩家。 ### 回應的重複使用 正式 URL 回傳 `true` 後,對於同一商家專案內同一接收者 ID 的後續驗證,Tokenz 可能不再呼叫您的伺服器而直接回應,預設持續幾分鐘。要自行決定時長,請在 `true` 回應中加入日期時間 `validUntil`: ```json { "valid": true, "validUntil": "2026-07-22T09:45:00Z" } ``` `false` 回應不會被重複使用,因此改正 ID 的玩家會重新驗證。 傳送到測試 URL 的驗證一律會送達您的伺服器。 ## 重試與冪等性 Tokenz 期望您的端點以 2xx 回應確認收到 Webhook。如果您的端點回傳其他狀態碼、逾時或無法連線,Tokenz 會在最多三天內自動重試投遞。首次重試大約會在投遞失敗後的 5 秒、15 秒和 30 秒進行。之後重試間隔會逐漸增加,頻率也會降低。重試時間可能略有變化;請勿依賴後續重試的精確時間表。一旦您的端點回傳 2xx,Tokenz 將停止重試該事件。您的端點可能會多次收到同一事件,且事件到達順序不受保證。 請以冪等方式處理投遞: - 先將事件持久儲存,再回傳 2xx 回應,並以非同步方式執行耗時的處理。 - 使用事件頂層的 `id` 作為冪等鍵: 記錄已處理的事件 ID 並跳過已處理過的事件,避免重試導致訂單被重複履行。 ## 疑難排解:我的端點沒有收到事件 絕大多數情況下,「Webhook 從未送達」其實意味著 Tokenz **確實**發送了它,而您的端點**拒絕**了它。Tokenz 會將任何非 `2xx` 的回應(或逾時、無法連線的端點)視為投遞失敗,並在最多三天內自動重試——因此在您這一側看起來像是什麼都沒收到,而 Tokenz 卻一直看到同一次投遞不斷失敗(例如連續出現一串 `HTTP 400`)。 如果主控台提供事件投遞紀錄,請開啟對應的事件或端點,查看投遞狀態、HTTP 回應與嘗試紀錄。能否查看取決於您的角色權限。如果沒有投遞紀錄,請透過伺服器的存取紀錄與錯誤紀錄排查。 **1. 檢查您的端點回傳的 HTTP 狀態碼。** 這正是 Tokenz 所看到的——請在伺服器的存取紀錄/錯誤紀錄中查找收到的 `POST` 請求。 - `2xx` — 事件已投遞並被確認。如果您的系統仍然沒有據此執行操作,那麼問題出在回應_之後_的處理器中,而不是投遞環節。 - `400`、`401`、`403` — 您的端點收到了事件但拒絕了它(見下文)。 - `5xx` 或逾時 — 您的處理器發生錯誤,或回應太慢。 **2. 如果您回傳的是 `400`,請先檢查簽名驗證**——這是最常見的原因: - **對原始請求本文進行驗證。** 大多數框架會解析並重新序列化 JSON,這會改變位元組內容並破壞 HMAC。請讀取確切的原始位元組(例如使用 `express.raw()`),先驗證,然後再解析。參見[保護您的 webhook 端點](https://docs.tokenz.one/zh-TW/v3/checkout/webhooks-get-started#3.-%E4%BF%9D%E8%AD%B7%E4%BD%A0%E7%9A%84-webhook-%E7%AB%AF%E9%BB%9E)。 - **使用正確的簽名金鑰。** 金鑰只在您註冊端點時顯示一次,並且是該端點專用的;被輪換或輸入錯誤的金鑰會導致每個事件都驗證失敗。 - **讓測試模式與正式模式相符。** 用正式模式的簽名金鑰去驗證測試模式的事件(或反過來)永遠不會相符。如果一個端點同時處理兩種模式,請根據事件的 `test` 旗標來選擇金鑰。 - **注意時鐘偏差。** 如果您依 5 分鐘的時間戳容許誤差進行拒絕,伺服器時鐘嚴重偏差可能會導致原本有效的事件被拒絕。 **3. 導致非 2xx 回應的其他原因:** - 端點前面的防火牆、WAF 或 IP 允許清單攔截了 Tokenz 的請求。 - 端點無法透過 **HTTPS** 公開存取,或在後台中註冊的 URL 有誤或指向了錯誤的環境。 - 在請求處理路徑中執行了繁重的工作導致逾時——請先用 `2xx` 確認收到,然後再非同步處理。 **4. 獨立確認投遞。** 將您的端點(或其副本)指向 [Webhook.site](https://webhook.site/),以確認 Tokenz 正在投遞,並檢查確切的有效酬載和 header,然後用測試模式付款觸發一個事件。 一旦您的端點回傳 `2xx`,重試就會停止。由於重試可能會重新發送您已經處理過的事件,請保持您的處理器冪等(見上文)。