이벤트 종류

페이리는 다음 5종 이벤트를 발행해요.
엔드포인트 등록 시 받을 이벤트를 골라요.

이벤트	발생 시점
`order.paid`	결제가 승인돼 주문이 `paid`가 됐을 때
`order.refunded`	환불이 발행됐을 때
`subscription.renewed`	구독이 갱신(재청구 성공)됐을 때
`subscription.payment_failed`	구독 재청구가 실패했을 때 (유예 상태 `past_due` 진입)
`subscription.canceled`	재청구 실패가 누적돼 구독이 종료됐을 때

본문 구조

모든 이벤트는 같은 봉투로 와요.
type으로 분기하고, 실제 내용은 data에서 읽으세요.


{
  "type": "order.paid",
  "data": { /* 이벤트별 페이로드 */ }
}

예약 해지가 주기 종료로 실제 종료될 때는 별도 웹훅이 오지 않아요.
해지 예약된 구독의 종료 시점은 GET /v1/subscriptions/:id의 scheduledChange.effectiveAt으로 확인하세요.

order.paid · order.refunded

data는 주문 객체 전체예요.
order.refunded에는 refunds·refundedAmount가 채워져 와요.
Checkout Session에서 시작된 주문이면 세션에 담은 metadata가 metadata 필드로 함께 와요.


{
  "type": "order.paid",
  "data": {
    "id": "ord_3kf9a2",
    "productId": "prod_88x",
    "productName": "MeetNote Solo",
    "amount": 19000,
    "currency": "KRW",
    "buyerEmail": "buyer@example.com",
    "method": "card",
    "status": "paid",
    "createdAt": "2026-06-16T03:20:00.000Z",
    "paidAt": "2026-06-16T03:20:05.000Z",
    "metadata": { "userUuid": "u_9f2c" }
  }
}

subscription.renewed


{
  "type": "subscription.renewed",
  "data": {
    "subscriptionId": "sub_77a",
    "orderId": "ord_9z1",
    "planId": "plan_solo",
    "billingInterval": "monthly",
    "amount": 9900
  }
}

subscription.payment_failed

attempts는 실패한 재청구 횟수예요.
구독은 past_due 상태로 유예되고, 다음 사이클에 다시 청구를 시도해요.


{
  "type": "subscription.payment_failed",
  "data": {
    "subscriptionId": "sub_77a",
    "attempts": 1,
    "amount": 9900,
    "planId": "plan_solo",
    "billingInterval": "monthly"
  }
}

subscription.canceled

재청구 실패가 누적돼 구독이 ended로 종료됐을 때 와요.
reason은 종료 경위예요. (현재는 billing_failed만)


{
  "type": "subscription.canceled",
  "data": {
    "subscriptionId": "sub_77a",
    "reason": "billing_failed",
    "attempts": 3
  }
}

테스트 발송(셀러 콘솔의 “테스트” 버튼)은 data에 _test: true가 붙어요.
실제 처리 로직에서 테스트 이벤트를 걸러내고 싶으면 이 필드를 확인하세요.

웹훅 본문은 알림용 스냅샷이에요.
중요한 처리 전에는 GET /v1/orders/:id나 GET /v1/subscriptions/:id로 최종 상태를 다시 확인하세요.