홈▸개발문서▸Webhooks▸Event Payloads

Webhook Event Payloads

SweetBook API에서 발생하는 5가지 웹훅 이벤트의 페이로드 구조와 예시를 안내합니다.

공통 페이로드 구조

모든 웹훅 이벤트는 아래의 공통 필드를 포함합니다.

필드타입설명
eventstring이벤트 타입 (예: order.paid)
orderUidstring주문 고유 ID (예: or_a1b2c3d4)
statusstring현재 주문 상태
timestampstring이벤트 발생 시각 (ISO 8601)
isTestbooleanSandbox 환경 여부

전송 헤더

모든 웹훅 요청에는 다음 헤더가 포함됩니다. 서명 검증 시 반드시 확인하세요.

헤더설명예시
X-Webhook-SignatureHMAC-SHA256 서명값 (hex)e3b0c44298fc1c14...
X-Webhook-Timestamp서명 생성 시점 (Unix timestamp, 초)1709280000
X-Webhook-Event이벤트 타입order.paid
X-Webhook-Delivery전송 고유 ID (중복 수신 확인용)wh_d7e8f9a0b1c2

전송 상태 (Delivery Status)

상태설명
PENDING전송 대기 또는 진행 중
SUCCESS전송 성공 (수신 서버가 2xx 응답)
FAILED전송 실패 (재시도 대기 중, 최대 3회)
EXHAUSTED최대 재시도 횟수(3회) 초과 — 수동 확인 필요

order.paid — 주문 생성 (충전금 차감 완료)

주문이 생성되고 충전금 차감이 완료되면 발생합니다. 내부 시스템에 주문 접수를 동기화하거나, 고객에게 주문 접수 알림을 보낼 때 활용합니다.

주요 필드

필드설명
bookUid제작 대상 도서 ID
quantity주문 수량
totalCredits차감된 충전금 합계
shippingAddress배송지 정보

예시 페이로드

json
{
  "event": "order.paid",
  "orderUid": "or_8f3a2b1c",
  "bookUid": "bk_e4d5c6b7",
  "status": "PAID",
  "quantity": 2,
  "totalCredits": 35000,
  "shippingAddress": {
    "recipientName": "홍길동",
    "phone": "010-1234-5678",
    "zipCode": "06234",
    "address1": "서울특별시 강남구 테헤란로 123",
    "address2": "4층 401호"
  },
  "isTest": false,
  "timestamp": "2025-03-15T10:30:00Z"
}

order.confirmed — 제작 확정

주문이 검수를 통과하여 제작이 확정되면 발생합니다. 고객에게 제작 시작 안내를 보내거나, 예상 완료일을 표시할 때 활용합니다.

주요 필드

필드설명
confirmedAt제작 확정 시각
estimatedShipDate예상 발송일

예시 페이로드

json
{
  "event": "order.confirmed",
  "orderUid": "or_8f3a2b1c",
  "bookUid": "bk_e4d5c6b7",
  "status": "CONFIRMED",
  "confirmedAt": "2025-03-15T14:00:00Z",
  "estimatedShipDate": "2025-03-20",
  "isTest": false,
  "timestamp": "2025-03-15T14:00:00Z"
}

order.status_changed — 주문 상태 변경

주문 상태가 변경될 때마다 발생하는 범용 이벤트입니다. 상태 이력을 추적하거나 대시보드를 실시간으로 업데이트할 때 활용합니다.previousStatus와 newStatus 필드로 변경 전후 상태를 확인할 수 있습니다.

주요 필드

필드설명
previousStatus변경 전 상태
newStatus변경 후 상태

예시 페이로드

json
{
  "event": "order.status_changed",
  "orderUid": "or_8f3a2b1c",
  "bookUid": "bk_e4d5c6b7",
  "status": "PRINTING",
  "previousStatus": "CONFIRMED",
  "newStatus": "PRINTING",
  "isTest": false,
  "timestamp": "2025-03-17T09:15:00Z"
}
order.status_changed는 다른 이벤트(order.paid, order.shipped 등)와 동시에 발생할 수 있습니다. 특정 상태에만 관심이 있다면 개별 이벤트를 구독하는 것이 더 효율적입니다.

order.shipped — 발송 완료

제작이 완료되어 택배사에 인계되면 발생합니다. 운송장 번호(trackingNumber)와 택배사 정보(trackingCarrier)가 포함되어 배송 추적을 시작하거나 고객에게 발송 알림을 보낼 때 활용합니다.

주요 필드

필드설명
trackingNumber운송장 번호
trackingCarrier택배사 코드 (예: CJ, HANJIN, LOTTE)
shippedAt발송 시각

예시 페이로드

json
{
  "event": "order.shipped",
  "orderUid": "or_8f3a2b1c",
  "bookUid": "bk_e4d5c6b7",
  "status": "SHIPPED",
  "trackingNumber": "1234567890123",
  "trackingCarrier": "CJ",
  "shippedAt": "2025-03-20T16:45:00Z",
  "isTest": false,
  "timestamp": "2025-03-20T16:45:00Z"
}

order.cancelled — 주문 취소

주문이 취소되면 발생합니다. 취소 사유와 충전금 환불 정보가 포함됩니다. 환불 처리나 내부 재고 복원 로직에 활용합니다.

주요 필드

필드설명
cancelledAt취소 시각
cancelReason취소 사유
refundedCredits환불된 충전금 금액

예시 페이로드

json
{
  "event": "order.cancelled",
  "orderUid": "or_8f3a2b1c",
  "bookUid": "bk_e4d5c6b7",
  "status": "CANCELLED",
  "cancelledAt": "2025-03-16T11:20:00Z",
  "cancelReason": "고객 요청에 의한 취소",
  "refundedCredits": 35000,
  "isTest": false,
  "timestamp": "2025-03-16T11:20:00Z"
}

관련 문서