샵바이에서 제공하는 웹훅(WebHook)에 대해 안내하기 위한 콘텐츠입니다.
업데이트 : 2023.10.25
목차
1. 웹훅(WebHook)이란
2. 주문정보 웹훅이란
-2.1. 주문생성 웹훅
-2.2. 주문상태 변경 웹훅
3. 사용 요청 어떻게 하나요?
1. 웹훅(WebHook)이란
개념설명
서버에서 특정 이벤트 발생 시 외부서버로 정보를 알릴 수 있는 매커니즘입니다.
Webhook은 서버에서 이벤트 발생 시 외부서버에서 미리 지정해놓은 callback URI에 POST HTTP로 이벤트 관련 정보를 보냅니다.
따라서 외부서버 입장에서는 지속적으로 데이터를 폴링(polling)하여 불필요한 정보를 받는 대신, Webhook을 활용하여 중요 이벤트가 발생했을 때만 정보를 수신하여 처리할 수 있습니다.
shopby에서 제공하는 웹훅은?
shopby에서는 아래 안내드릴 '주문정보 웹훅'을 제공하고 있습니다.
2. 주문정보 웹훅이란?
요약
shopby에서 1) 새로운 주문이 발생하거나2) 주문의 상태가 변경될 때
상태가 변경된 주문의 정보를 웹훅을 통해 등록된 고객사의 외부 URI로 알려주는 REST API call입니다.
지원 가능한 method: POST / PUT
웹훅 발행시점
주문정보 웹훅에는 아래 2가지 유형의 이벤트가 있습니다.
주문 생성
→ 고객이 주문을 최초 생성했을 때 생성된 주문의 정보를 웹훅을 통해 전달
주문상태 변경
→ 주문상태(orderStatusType) 또는 클레임상태(claimStatusType)가 변경되었을 때 정보를 웹훅을 통해 전달
주문 상태 (orderStatusType)
주문생성 또는 주문상태 변경 웹훅 Request Body 내 주문상태(orderStatusType)에 포함된 코드는 아래와 같습니다.
구분
주문상태코드
한글명
비고
정상상태
DEPOSIT_WAIT
입금대기
무통장, 가상계좌 거래인 경우 입금 전 상태
정상상태
PAY_DONE
결제완료
결제를 완료한 상태
정상상태
PRODUCT_PREPARE
상품준비중
상품을 보낼 준비를 하는 boxing 단계
정상상태
DELIVERY_PREPARE
배송준비중
송장번호를 할당하는 단계
정상상태
DELIVERY_ING
배송중
택배를 보낸 상태
정상상태
DELIVERY_DONE
배송완료
택배가 도착한 상태
정상상태
BUY_CONFIRM
구매확정
고객이 구매확정 했거나, 구매확정이 자동완료 된 상태
클레임상태
CANCEL_DONE
취소완료
배송 전 취소 신청하여 환불이 완료된 상태
클레임상태
RETURN_DONE
반품완료
배송 후 반품되어 환불이 완료된 상태
클레임상태
EXCHANGE_DONE
교환완료
교환이 완료된 상태
* 클레임상태(claimStatusType)에 포함된 코드는 회원 클레임 목록 조회하기 API에서 claimStatusType Eunm에 표시된 코드를 참고해 주시기 바랍니다.
2.1 주문생성
발행 시점
주문발생 시 (입금대기 또는 결제 완료)
단 배송 없이 주문되는 상품일 경우, 주문생성과 동시에 배송완료(DELIVERY_DONE)로 처리됩니다.
'(2-2) 주문상태 변경 웹훅'과 차이점
주문생성 웹훅은 주문단위로, 여러 개의 주문 상품과 각 주문상품 내 여러 옵션이 하나로 묶여서 처리됩니다.
