--- title: "在您的 Webhook 端点接收 Tokenz 事件" description: "通过 Webhook 接收 Tokenz 账户中的事件,让您的系统自动执行后续操作。" source: "https://docs.tokenz.one/zh-CN/v3/checkout/webhooks" api_version: "v3" locale: "zh-CN" version_status: "current" docs_stage: "prod" --- # 在您的 Webhook 端点接收 Tokenz 事件 通过 Webhook 接收 Tokenz 账户中的事件,让您的系统自动执行后续操作。 **金额格式:** Webhook 负载中的所有货币值(如 `amount` 字段)均以各货币的最小单位表示。请参阅[支持的货币](https://docs.tokenz.one/zh-CN/v3/checkout/currency)了解每种货币的确切编码。 ## 为什么使用 Webhook 接入 Tokenz Checkout 时,应用程序需要接收账户中的事件,并由后端执行相应操作。 要启用 Webhook 事件,您需要注册 Webhook 端点。注册完成后,Tokenz 会在事件发生时,将实时的事件数据推送到您的应用程序的 Webhook 端点。Tokenz 通过 HTTPS 将事件以包含 Event 对象的 JSON 格式发送给您的应用程序。 我们强烈建议除了处理 Checkout 重定向外,还实现 Webhook,以确保您始终能收到 Checkout 结果的通知。 ## Event 对象 当事件发生时,Tokenz 会生成一个新的 Event 对象。一次 API 请求可能会生成多个事件。 通过在 Tokenz 账户中注册 Webhook 端点,您可以让 Tokenz 自动将 Event 对象作为 POST 请求的一部分发送到您应用程序托管的 Webhook 端点。当您的 Webhook 端点收到 Event 后,您的应用程序可以执行后端操作(例如,在收到 order.succeeded 事件后,向客户发送购买商品的下载链接或为他们的账户充值)。 我们发送到您 Webhook 端点的 Event 对象提供了已更改对象的快照。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` | 当通过 [Create a Checkout Session](https://docs.tokenz.one/zh-CN/v3/api/main) API 创建一个新的 order 对象时触发。 | | `order.succeeded` | 当消费者成功支付一笔 `order` 时触发,这时您可以向客户提供产品。 | | `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-CN/v3/checkout/webhooks#player-id-checks)。 ## 接收者 ID 验证 玩家在您的 Tokenz 网店中输入接收者 ID 后,网店会在玩家购买或领取免费物品之前验证该 ID。每次验证时,Tokenz 都会发送 `user.validation` 请求,询问您的服务器该接收者 ID 对应的账号是否存在;如果可以复用之前的答复,则不会发送(参见[应答的复用](https://docs.tokenz.one/zh-CN/v3/checkout/webhooks#player-id-check-reuse))。Tokenz 从响应中读取您的答复,最多等待 3 秒,并且从不重试。创建 Checkout Session 不会发送它,无论是通过 API 还是从网店创建。 完整的请求和响应结构,请参阅 [User validation API 参考](https://docs.tokenz.one/zh-CN/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-CN/v3/checkout/webhooks-get-started#3.-%E4%BF%9D%E6%8A%A4%E4%BD%A0%E7%9A%84-webhook-%E7%AB%AF%E7%82%B9)。 ### 您的应答 以 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-CN/v3/checkout/webhooks-get-started#3.-%E4%BF%9D%E6%8A%A4%E4%BD%A0%E7%9A%84-webhook-%E7%AB%AF%E7%82%B9)。 - **使用正确的签名密钥。** 密钥只在你注册端点时显示一次,并且是该端点专用的;被轮换或输入错误的密钥会导致每个事件都验证失败。 - **匹配测试模式和正式模式。** 用正式模式的签名密钥去验证测试模式的事件(或反过来)永远不会匹配。如果一个端点同时处理两种模式,请根据事件的 `test` 标志来选择密钥。 - **注意时钟偏差。** 如果你按 5 分钟的时间戳容差进行拒绝,服务器时钟严重偏差可能会导致原本有效的事件被拒绝。 **3. 导致非 2xx 响应的其他原因:** - 端点前面的防火墙、WAF 或 IP 允许列表拦截了 Tokenz 的请求。 - 端点无法通过 **HTTPS** 公开访问,或在控制台中注册的 URL 有误或指向了错误的环境。 - 在请求处理路径中执行了繁重的工作导致超时——请先用 `2xx` 确认收到,然后再异步处理。 **4. 独立确认投递。** 将你的端点(或其副本)指向 [Webhook.site](https://webhook.site/),以确认 Tokenz 正在投递,并检查确切的有效负载和标头,然后用测试模式付款触发一个事件。 一旦你的端点返回 `2xx`,重试就会停止。由于重试可能会重新发送你已经处理过的事件,请保持你的处理器幂等(见上文)。