在 Webhook 端點接收 Tokenz 事件
透過 Webhook 接收 Tokenz 帳戶中的事件,讓您的系統自動執行後續處理。
金額格式: Webhook 酬載中的所有貨幣值(如 amount 欄位)均以各貨幣的最小單位表示。請參閱支援的貨幣以了解每種貨幣的確切編碼。
為何使用 Webhook
串接 Tokenz Checkout 時,應用程式需要接收帳戶中的事件,再由後端執行相應操作。
先註冊 Webhook 端點。之後帳戶中發生事件時,Tokenz 會透過 HTTPS,以 JSON 格式將事件資料傳送到您的應用程式。
除了處理結帳完成後的重新導向,也建議串接 Webhook,以接收付款結果通知。
事件概述
Tokenz 會透過事件通知您帳戶中的活動。
事件發生時,Tokenz 會建立新的事件物件。一次 API 請求可能產生多個事件。
註冊 Webhook 端點後,Tokenz 會透過 POST 請求將事件物件傳送到該端點。應用程式收到事件後即可執行後續處理,例如收到 order.succeeded 後發放遊戲物品。
事件物件
傳送到 Webhook 端點的事件物件包含相關物件的快照,以及事件的中繼資料。
查看我們發送到您 webhook 的事件類型完整列表。
事件酬載(payload)範例
以下範例是訂單付款成功後傳送的事件。
{
"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 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 驗證。
接收者 ID 驗證
玩家在您的 Tokenz 商城中輸入接收者 ID 後,商城會在玩家購買或領取免費物品之前驗證該 ID。每次驗證時,Tokenz 都會傳送 user.validation 請求,詢問您的伺服器該接收者 ID 對應的帳號是否存在;如果可以重複使用先前的答覆,則不會傳送(請參閱回應的重複使用)。Tokenz 從回應中讀取您的答覆,最多等待 3 秒,而且從不重試。建立 Checkout Session 不會傳送它,無論是透過 API 還是從商城建立。
完整的請求與回應結構請參閱 User validation API 參考。
設定驗證 URL
- 在 設定 > 開發者 > 使用者驗證 中設定 URL。測試和正式各有自己的 URL 和簽章金鑰,請先把主控台切換到要設定的模式。簽章金鑰只會在產生時顯示一次。
- Tokenz 只會把
user.validation傳送到這個 URL。Webhook 端點不會收到它,即使是接收所有事件的端點。 - 要檢查您的伺服器,請輸入遊戲中的接收者 ID 並選擇 傳送測試驗證。主控台會顯示伺服器的回覆。Tokenz 不會保存任何內容。
- 設定正式驗證 URL 之前,您的商城無法在正式環境中啟用。
正式商城中的購買由您的正式 URL 驗證,test 為 false。測試預覽中的購買由您的測試 URL 驗證,test 為 true。如果沒有設定測試 URL,測試預覽會不經驗證直接接受輸入的 ID。
請求
Tokenz 傳送一個帶 JSON 內文的 POST:
{
"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 端點。
您的回應
以 HTTP 200 回應,並說明玩家是否存在:
{ "valid": true }
{ "valid": false }
- 無論玩家是否存在,都回傳
200。Tokenz 會把 2xx 以外的狀態碼(包括重新導向)或不含valid的內文視為服務故障,而不是未知玩家。 - 在 3 秒內回應。如果 Tokenz 未能及時取得判定,玩家將無法付款,並會被提示再試一次。下文的重試與冪等性僅適用於事件。
- 只回傳
valid和選填的validUntil,不要包含玩家詳情。玩家可以得知驗證是否通過,但 Tokenz 不會將伺服器的原始回應轉送給玩家。
回應的重複使用
正式 URL 回傳 true 後,對於同一商家專案內同一接收者 ID 的後續驗證,Tokenz 可能不再呼叫您的伺服器而直接回應,預設持續幾分鐘。要自行決定時長,請在 true 回應中加入日期時間 validUntil:
{ "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 端點。 - 使用正確的簽名金鑰。 金鑰只在您註冊端點時顯示一次,並且是該端點專用的;被輪換或輸入錯誤的金鑰會導致每個事件都驗證失敗。
- 讓測試模式與正式模式相符。 用正式模式的簽名金鑰去驗證測試模式的事件(或反過來)永遠不會相符。如果一個端點同時處理兩種模式,請根據事件的
test旗標來選擇金鑰。 - 注意時鐘偏差。 如果您依 5 分鐘的時間戳容許誤差進行拒絕,伺服器時鐘嚴重偏差可能會導致原本有效的事件被拒絕。
3. 導致非 2xx 回應的其他原因:
- 端點前面的防火牆、WAF 或 IP 允許清單攔截了 Tokenz 的請求。
- 端點無法透過 HTTPS 公開存取,或在後台中註冊的 URL 有誤或指向了錯誤的環境。
- 在請求處理路徑中執行了繁重的工作導致逾時——請先用
2xx確認收到,然後再非同步處理。
4. 獨立確認投遞。 將您的端點(或其副本)指向 Webhook.site,以確認 Tokenz 正在投遞,並檢查確切的有效酬載和 header,然後用測試模式付款觸發一個事件。
一旦您的端點回傳 2xx,重試就會停止。由於重試可能會重新發送您已經處理過的事件,請保持您的處理器冪等(見上文)。