Webhook Events 레퍼런스

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

공통 페이로드 구조

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

필드타입설명
event_uidstring이벤트 고유 ID
event_typestring이벤트 타입 (예: order.created)
created_atstring이벤트 발생 시각 (ISO 8601)
dataobject이벤트별 페이로드 데이터

전송 헤더

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

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

전송 상태 (Delivery Status)

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

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

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

주요 필드 (data)

필드설명
order_uid주문 고유 ID
order_status주문 상태
total_amount주문 총액
item_count주문 항목 수
ordered_at주문 시각
order.created
{
  "event_uid": "evt_a1b2c3d4",
  "event_type": "order.created",
  "created_at": "2025-03-15T10:30:00Z",
  "data": {
    "order_uid": "or_8f3a2b1c",
    "order_status": "PAID",
    "total_amount": 35000,
    "item_count": 2,
    "ordered_at": "2025-03-15T10:30:00Z"
  }
}

order.cancelled — 주문 취소

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

주문 항목 부분 취소(POST /orders/{orderUid}/items/{itemUid}/cancel)로 마지막 항목까지 취소되어 주문 전체가 취소되는 경우에도 호환 목적으로 order.cancelled가 함께 발송됩니다. 이때는 order.item_cancelled(full_cancel: true)도 같이 발송됩니다.

주요 필드 (data)

필드설명
order_uid주문 고유 ID
order_status주문 상태
cancel_reason취소 사유
refund_amount환불 금액
cancelled_at취소 시각
order.cancelled
{
  "event_uid": "evt_b2c3d4e5",
  "event_type": "order.cancelled",
  "created_at": "2025-03-16T11:20:00Z",
  "data": {
    "order_uid": "or_8f3a2b1c",
    "order_status": "CANCELLED",
    "cancel_reason": "고객 요청에 의한 취소",
    "refund_amount": 35000,
    "cancelled_at": "2025-03-16T11:20:00Z"
  }
}

order.item_cancelled — 주문 항목 부분 취소

주문에 포함된 개별 항목이 부분 취소(POST /orders/{orderUid}/items/{itemUid}/cancel)될 때 발생합니다. 환불 처리나 항목 단위 재고 복원 로직에 활용합니다.

full_cancel이 true이면 이번 호출이 마지막 항목 취소로 이어져 주문 전체가 취소된 경우입니다. 이때는 호환 목적으로 order.cancelled도 함께 발송되므로, 두 이벤트를 모두 구독 중이라면 중복 처리되지 않도록 event_uid 기반으로 처리하세요.

주요 필드 (data)

필드설명
order_uid주문 고유 ID
order_status처리 후 주문 상태 (부분 취소 시 20/25 유지, 전체 취소 귀결 시 81)
full_cancel이번 호출이 전체 취소로 귀결됐는지 여부 (true/false)
cancelled_item_uid이번 호출로 취소된 항목 UID
remaining_item_uids남은(살아있는) 항목 UID 배열
cancel_reason취소 사유
refund_amount이번 호출로 환불된 금액 (원, decimal)
cancelled_at취소 시각 (ISO 8601, UTC)
order.item_cancelled (부분 취소)
{
  "event_uid": "evt_c3d4e5f6",
  "event_type": "order.item_cancelled",
  "created_at": "2026-04-22T01:23:00Z",
  "data": {
    "order_uid": "or_2lnj********",
    "order_status": "PAID",
    "full_cancel": false,
    "cancelled_item_uid": "oi_6bGM********",
    "remaining_item_uids": ["oi_1Nrc********"],
    "cancel_reason": "고객 요청 (1권 제외)",
    "refund_amount": 110.00,
    "cancelled_at": "2026-04-22T01:23:00Z"
  }
}
order.item_cancelled (전체 취소 귀결)
{
  "event_uid": "evt_d4e5f6g7",
  "event_type": "order.item_cancelled",
  "created_at": "2026-04-22T01:21:38Z",
  "data": {
    "order_uid": "or_184U********",
    "order_status": "CANCELLED_REFUND",
    "full_cancel": true,
    "cancelled_item_uid": "oi_34Hu********",
    "remaining_item_uids": [],
    "cancel_reason": "Test full cancel via partial",
    "refund_amount": 3410.00,
    "cancelled_at": "2026-04-22T01:21:38Z"
  }
}

order.restored — 주문 복원

취소된 주문이 복원(취소 철회)되면 발생합니다. 복원 시 충전금이 다시 차감됩니다.

주요 필드 (data)

필드설명
order_uid주문 고유 ID
order_status주문 상태 (문자열 enum)
restore_reason복원 사유
restored_at복원 시각
credit_deducted복원 시 충전금 재차감 여부 (boolean)
order.restored
{
  "event_uid": "evt_c3d4e5f6",
  "event_type": "order.restored",
  "created_at": "2026-03-16T13:00:00Z",
  "data": {
    "order_uid": "or_8f3a********",
    "order_status": "PAID",
    "restore_reason": "파트너 요청으로 복원",
    "restored_at": "2026-03-16T13:00:00Z",
    "credit_deducted": true
  }
}

페이로드에는 SweetBook 관리자 내부 입력 필드(restored_by)가 함께 전송될 수 있으나, 파트너 측 처리에는 의미가 없으므로 무시하면 됩니다.

production.confirmed — 제작 확정

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

주요 필드 (data)

필드설명
order_uid주문 고유 ID
order_status주문 상태
print_day출력 예정일
confirmed_at제작 확정 시각
production.confirmed
{
  "event_uid": "evt_d4e5f6g7",
  "event_type": "production.confirmed",
  "created_at": "2025-03-15T14:00:00Z",
  "data": {
    "order_uid": "or_8f3a2b1c",
    "order_status": "CONFIRMED",
    "print_day": "2025-03-20",
    "confirmed_at": "2025-03-15T14:00:00Z"
  }
}

production.started — 제작 시작

인쇄 제작이 시작되면 발생합니다. 제작 진행 중임을 고객에게 안내할 때 활용합니다.

주요 필드 (data)

필드설명
order_uid주문 고유 ID
order_status주문 상태
changed_at상태 변경 시각
production.started
{
  "event_uid": "evt_e5f6g7h8",
  "event_type": "production.started",
  "created_at": "2025-03-17T09:00:00Z",
  "data": {
    "order_uid": "or_8f3a2b1c",
    "order_status": "IN_PRODUCTION",
    "changed_at": "2025-03-17T09:00:00Z"
  }
}

production.completed — 제작 완료

모든 제작이 완료되어 배송 준비 단계에 진입하면 발생합니다.

주요 필드 (data)

필드설명
order_uid주문 고유 ID
order_status주문 상태
completed_at제작 완료 시각
production.completed
{
  "event_uid": "evt_f6g7h8i9",
  "event_type": "production.completed",
  "created_at": "2025-03-19T17:30:00Z",
  "data": {
    "order_uid": "or_8f3a2b1c",
    "order_status": "PRODUCTION_COMPLETE",
    "completed_at": "2025-03-19T17:30:00Z"
  }
}

shipping.departed — 발송 완료

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

주요 필드 (data)

필드설명
order_uid주문 고유 ID
item_uid주문 항목 고유 ID
tracking_number운송장 번호
tracking_carrier택배사 코드 (예: CJ, HANJIN, LOTTE)
shipped_at발송 시각
shipping.departed
{
  "event_uid": "evt_g7h8i9j0",
  "event_type": "shipping.departed",
  "created_at": "2025-03-20T16:45:00Z",
  "data": {
    "order_uid": "or_8f3a2b1c",
    "item_uid": "oi_x1y2z3",
    "tracking_number": "1234567890123",
    "tracking_carrier": "CJ",
    "shipped_at": "2025-03-20T16:45:00Z"
  }
}

shipping.delivered — 배송 완료

배송이 완료되면 발생합니다. 배송 완료 안내 또는 리뷰 요청에 활용합니다.

주요 필드 (data)

필드설명
order_uid주문 고유 ID
order_status주문 상태
changed_at상태 변경 시각
shipping.delivered
{
  "event_uid": "evt_h8i9j0k1",
  "event_type": "shipping.delivered",
  "created_at": "2025-03-22T14:00:00Z",
  "data": {
    "order_uid": "or_8f3a2b1c",
    "order_status": "DELIVERED",
    "changed_at": "2025-03-22T14:00:00Z"
  }
}

관련 문서