구독 웹훅

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

엔드포인트 등록, 서명 검증, 라이브·테스트 모드 처리는 웹훅과 웹훅 연동을 참고하세요. 구독 이벤트도 주문, 환불, 분쟁, 코드 사용 이벤트와 같은 Event 구조 및 전송 방식을 사용합니다.

금액 형식: 웹훅의 금액은 각 통화의 최소 단위로 표시됩니다. 지원 통화를 참고하세요.

이벤트 페이로드 예제

다음은 구독 갱신 성공 시 전송되는 이벤트의 예제입니다.

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: 현재 청구 기간 종료 시(또는 상품 정책에 따라 즉시) 권한을 회수하고 자체 상태를 최종 상태로 변경하세요.