订阅 Webhook

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

关于如何注册 webhook 端点、验证签名以及处理正式/测试模式，请参见 Webhook 和开始使用 Webhook——订阅事件使用与订单、退款、争议和兑换事件完全相同的事件信封和投递机制。

金额格式： webhook 负载中的金额以每种货币的最小辅助单位表示。参见支持的货币。

示例事件负载

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

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: 订阅因始终无法收款（催收已耗尽，或初始扣款从未成功）而终止。

浏览文档

订阅 Webhook

示例事件负载

事件类型

推荐处理方式