---
title: "구독 웹훅"
description: "모든 구독 상태 전환은 웹훅으로 전송되므로 폴링 없이 백엔드를 동기화할 수 있습니다. 구독 전용 이벤트와 페이로드 구조를 설명합니다."
source: "https://docs.tokenz.one/ko-KR/v2/subscriptions/webhooks"
api_version: "v2"
locale: "ko-KR"
version_status: "current"
docs_stage: "prod"
---

# 구독 웹훅

모든 구독 상태 전환은 웹훅으로 전송되므로 폴링 없이 백엔드를 동기화할 수 있습니다. 구독 전용 이벤트와 페이로드 구조를 설명합니다.

엔드포인트 등록, 서명 검증, 라이브·테스트 모드 처리는 [웹훅](https://docs.tokenz.one/ko-KR/v2/checkout/webhooks)과 [웹훅 연동](https://docs.tokenz.one/ko-KR/v2/checkout/webhooks-get-started)을 참고하세요. 구독 이벤트도 주문, 환불, 분쟁, 코드 사용 이벤트와 같은 Event 구조 및 전송 방식을 사용합니다.

**금액 형식:** 웹훅의 금액은 각 통화의 최소 단위로 표시됩니다. [지원 통화](https://docs.tokenz.one/ko-KR/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` | 첫 청구가 성공했습니다(체험 없는 Checkout 또는 체험 종료 시). 구독은 `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`**: 필요하면 자체 UI에 결제 문제를 알리세요. Tokenz가 재시도와 고객 이메일을 자동 처리합니다.
- **`subscription.payment_method_updated`**: 결제 수단 메타데이터를 캐시한다면 자체 기록을 업데이트하세요. 정상 청구 유지를 위한 추가 조치는 없습니다.
- **`subscription.plan_changed`**: 새 요금제 아이템에 맞춰 이용 권한을 업데이트하세요.
- **`subscription.canceled`**, **`subscription.expired`**: 현재 청구 기간 종료 시(또는 상품 정책에 따라 즉시) 권한을 회수하고 자체 상태를 최종 상태로 변경하세요.