---
title: "订阅 Webhook"
description: "订阅会针对每一次生命周期转换发送 webhook 事件，让您的后端无需轮询即可保持同步。本页列出了订阅相关的专属事件及其负载结构。"
source: "https://docs.tokenz.one/zh-CN/v2/subscriptions/webhooks"
api_version: "v2"
locale: "zh-CN"
version_status: "current"
docs_stage: "prod"
---

# 订阅 Webhook

订阅会针对每一次生命周期转换发送 webhook 事件，让您的后端无需轮询即可保持同步。本页列出了订阅相关的专属事件及其负载结构。

关于如何注册 webhook 端点、验证签名以及处理正式/测试模式，请参见 [Webhook](https://docs.tokenz.one/zh-CN/v2/checkout/webhooks) 和[开始使用 Webhook](https://docs.tokenz.one/zh-CN/v2/checkout/webhooks-get-started)——订阅事件使用与订单、退款、争议和兑换事件完全相同的事件信封和投递机制。

**金额格式：** webhook 负载中的金额以每种货币的最小辅助单位表示。参见[支持的货币](https://docs.tokenz.one/zh-CN/v2/checkout/currency)。

## 示例事件负载

以下示例展示了订阅成功续订时发送的事件。

```json
{
  "id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "object": "subscription.renewed",
  "createdAt": "2026-07-01T00:00:00Z",
  "test": false,
  "eventData": {
    "type": "subscription",
    "version": "v2",
    "data": {
      "subscription": {
        "id": "subscription_1p4LS47fB1h",
        "object": "subscription",
        "status": "active",
        "test": false,
        "items": [
          {
            "id": "item_1p4LS47fB1i",
            "detail": {
              "product": {
                "price": { "amount": 1000, "currency": "USD" },
                "quantity": 1,
                "label": "Pro Plan (Monthly)",
                "images": ["https://example.com/pro-plan.png"]
              }
            }
          }
        ],
        "interval": { "unit": "MONTH", "count": 1 },
        "currentBillingPeriodEnd": "2026-08-01T00:00:00Z",
        "createdAt": "2026-06-01T00:00:00Z",
        "updatedAt": "2026-07-01T00:00:00Z"
      }
    }
  }
}
```

负载中始终包含事件发生时订阅的完整当前状态（而非差异）。请使用顶层的 `id` 进行投递追踪和幂等处理，并使用 `eventData.data.subscription.id` 将事件与您自己的记录相关联。

## 事件类型

| 类型 | 说明 |
| --- | --- |
| `subscription.trial_started` | 消费者提供了卡片信息并开始了订阅的试用期。订阅现在为 `trialing`。 |
| `subscription.activated` | 订阅的首次扣款成功（可能是在无试用期的结账时，也可能是在试用期结束时）。订阅现在为 `active`。 |
| `subscription.renewed` | 一次周期性续订扣款成功，订阅进入下一个计费周期。 |
| `subscription.unpaid` | 一次周期性（或初始）扣款失败或需要付款。订阅现在为 `unpaid`，催收流程已开始。 |
| `subscription.payment_method_updated` | 订阅的支付方式已成功更新（新卡片的授权已获批准）。 |
| `subscription.plan_change_scheduled` | 一次递延方案变更已获消费者批准，将在下一个计费周期开始时生效。 |
| `subscription.plan_change_canceled` | 一次先前排期的递延方案变更在生效前被取消。 |
| `subscription.plan_changed` | 一次方案变更（立即或递延）已应用到订阅。负载中的 `items` 和/或 `interval` 反映了新方案。 |
| `subscription.canceled` | 订阅已由商户代表消费者取消。之后不会再产生任何扣款。 |
| `subscription.expired` | 订阅因始终无法收款（催收已耗尽，或初始扣款从未成功）而终止。 |

## 推荐处理方式

- **`subscription.activated`** 和 **`subscription.renewed`**：为当前计费周期授予或延长产品访问权限。
- **`subscription.unpaid`**：可以选择在您自己的产品界面中提醒消费者注意支付问题；Tokenz 已经自动处理了重试和向消费者发送邮件的工作。
- **`subscription.payment_method_updated`**：如果您缓存了支付方式的元数据，请更新您自己的记录；无需其他操作即可保持订阅正常计费。
- **`subscription.plan_changed`**：更新权益以匹配新方案的商品。
- **`subscription.canceled`** 和 **`subscription.expired`**：在当前计费周期结束时（或根据您产品的策略立即）撤销访问权限，并更新您自己的订阅状态以反映该终止状态。