---
title: "訂閱 Webhook"
description: "訂閱會針對每一次生命週期轉換發送 webhook 事件，讓您的後端無需輪詢即可保持同步。本頁列出了訂閱相關的專屬事件及其負載結構。"
source: "https://docs.tokenz.one/zh-TW/v2/subscriptions/webhooks"
api_version: "v2"
locale: "zh-TW"
version_status: "current"
docs_stage: "prod"
---

# 訂閱 Webhook

訂閱會針對每一次生命週期轉換發送 webhook 事件，讓您的後端無需輪詢即可保持同步。本頁列出了訂閱相關的專屬事件及其負載結構。

關於如何註冊 webhook 端點、驗證簽章以及處理正式/測試模式，請參見 [Webhook](https://docs.tokenz.one/zh-TW/v2/checkout/webhooks) 和[開始使用 Webhook](https://docs.tokenz.one/zh-TW/v2/checkout/webhooks-get-started)——訂閱事件使用與訂單、退款、爭議和兌換事件完全相同的事件信封與傳遞機制。

**金額格式：** webhook 負載中的金額以每種貨幣的最小輔助單位表示。參見[支援的貨幣](https://docs.tokenz.one/zh-TW/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`**：在目前計費週期結束時（或根據您產品的政策立即）撤銷存取權限，並更新您自己的訂閱狀態以反映該終止狀態。