[웹훅 추가] 주문정보 웹훅(Webhook)이란?

샵바이에서 제공하는 웹훅(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가지 유형의 이벤트가 있습니다.

1. 주문 생성 → 고객이 주문을 최초 생성했을 때 생성된 주문의 정보를 웹훅을 통해 전달

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) 주문상태 변경 웹훅'과 차이점

  • 주문생성 웹훅은 주문단위로, 여러 개의 주문 상품과 각 주문상품 내 여러 옵션이 하나로 묶여서 처리됩니다.

  • Request Body에 결제정보 관련 주문 정보를 함께 전달합니다.

• Request Body

{
    "eventType": "CREATE_ORDER", //이벤트명
    "order": {
            "orderNo": "2021100201234567890", // 주문번호
            "mallNo": 30973, // 몰번호
            "serviceNo": 30388, // 서비스 번호
            "memberNo": 8411244, // 회원번호
            "memberYn": "Y", // 회원여부
            "ordererName": "홍길동", // 주문자명
            "ordererContact1": "010-1234-1234", // 주문자 핸드폰 번호
            "ordererContact2": "010-1234-1234", // 주문자 전화 번호
            "ordererEmail": "[[e-mail]](mailto:[e-mail])", // 주문자 이메일
            "payType": "CREDIT_CARD", // PG타입(페이코/KCP 등)
            "pgType": "KCP", // 결제타입(페이코/신용카드 등)
            "platformType": "MOBILE_WEB", // 플렛폼 타입 (PC/MOBILE_WEB 등)
            "lastPayAmt": 185000.00, // 최종결제금액
            "lastSubPayAmt": 0.00, // 최종 적립금 결제금액
            "lastStandardAmt": 329000.00, // 최종상품금액(할인제외)
            "lastDeliveryAmt": 0.00, // 최종배송금액
            "lastRemoteDeliveryAmt": 0.00, // 최종지역별추가배송금액
            "lastImmediateDiscountAmt": 144000.00, // 최종즉시할인금액
            "lastAdditionalDiscountAmt": 0.00, // 최종추가할인금액
            "lastCartCouponDiscountAmt": 0.00, // 최종주문쿠폰할인금액
            "lastProductCouponDiscountAmt": 0.00, // 최종상품쿠폰할인금액
            "lastTaxFreeAmt": 0.00, // 최종비과세금액
            "lastTaxableAmt": 168181.00, // 최종과세금액
            "lastVatAmt": 16819.00, // 최종부과세액
            "firstSalesTaxAmt": 0.00, // 최초부과세액
            "lastSalesTaxAmt": 0.00, // 최종부과세액
            "firstCustomsDutyAmt": 0.00, // 최초관부가세
            "lastCustomsDutyAmt": 0.00, // 최종관부가세
            "registerYmdt": "2021-10-25 13:53:18", // 등록일
            "trackingKey": "trackingKey", // 쇼핑채널링-추적키
            "cartCouponIssueNo": 12, // 장바구니쿠폰 발급 번호
            "extraData": "", // 추가 정보
            "orderProducts": [
                    {
                            "orderProductNo": 50000000, // 주문상품번호
                            "mallProductNo": 100000000, // 상품번호
                            "productName": "상품명",
                            "productManagementCd": "", // 상품관리 코드
                            "hsCode": "",
                            "eanCode": null,
                            "partnerNo": 50000, // 파트너 번호
                            "lastProductCouponDiscountAmt": 0.00, // 상품 쿠폰 할인액
                            "productCouponIssueNo": 13, // 사용한 상품 쿠폰 번호
                            "orderProductOptions": [
                              {
                                "orderProductOptionNo": 5062925, // 주문상품옵션번호
                                "orderNo": "2021100201234567890", // 주문번호
                                "memberNo": 100000, // 회원번호
                                "serviceNo": 30000, // 서비스 번호
                                "mallNo": 1000, // 몰번호
                                "mallProductNo": 10000000, // 상품번호
                                "productName": "상품명",
                                "mallOptionNo": 6000000, // 상품옵션번호
                                "mallAdditionalProductNo": 0, // 추가 상품 번호
                                "optionUseYn": "Y", // 옵션 사용 여부
                                "optionName": "옵션명",
                                "optionValue": "옵션값",
                                "imageUrl": "//rlyfaazj0.toastcdn.net/...", // 상품 이미지 url
                                "orderCnt": 1, // 주문건수
                                "originalOrderCnt": 1, // 최초 주문 수량
                                "salePrice": 329000.00, // 판매 가격
                                "immediateDiscountAmt": 144000.00, // 즉시 할인 가격
                                "addPrice": 0.00, // 추가 금액
                                "additionalDiscountAmt": 0.00, // 추가 할인 금액
                                "partnerChargeAmt": 0.00, // 파트너 부담액
                                "adjustedAmt": 185000.00, // 조정된 상품 금액
                                "orderStatusType": "PAY_DONE", // 주문옵션상태
                                "claimStatusType": null, // 클레임 상태
                                "orderYmdt": "2021-10-25 13:53:18", // 주문일시
                                "payYmdt": "2021-10-25 13:54:38", // 결제일시
                                "orderAcceptYmdt": null, // 주문접수일시
                                "releaseReadyYmdt": null, // 배송준비일시
                                "releaseYmdt": null, // 배송일시
                                "deliveryCompleteYmdt": null, // 배송완료일시
                                "buyConfirmYmdt": null, // 구매확정일시
                                "registerYmdt": "2021-10-25 13:53:18", // 주문옵션 생성일시
                                "trackingKey": "platform=MO&rid=851184319&aid=641_1_3_1025&mid=TMS", // 주문추적키 (쇼핑몰에서 생성되어 주문번호를 특정하는 구분값)
                                "deliveryNo": 400000, // 배송번호
                                "optionManagementCd": "", // 옵션 관리 코드
                                "isFreeGift": false, // 사은품 여부
                                "deliveryTemplateNo": 50000, // 배송 템플릿 번호
                                "deliveryCompanyType": "CJ", // 배송 업체
                                "invoiceNo": null, // 송장번호
                                "receiverName": "홍길동", // 받는 사람 이름
                                "usesShippingInfoLaterInput": false, // 나중배송지 입력 여부
                                "shippingInfoLaterInputContact": null, // 나중배송지 입력 전화 번호
                                "encryptedShippingNo": null, // 나중배송지 입력 시 사용하는 암호화된 배송번호
                                "shippingEmptAutoCancelYmdt" : "2023-10-25 13:54:38", // 배송지 미입력 시 자동 주문취소 일시
                              }
                            ]
                    }
            ]
    },
    "pay": {
            "pgType": "KCP", // PG 타입
            "payType": "CREDIT_CARD", // 결제 유형
            "payYmdt": "2021-10-25 13:54:38", // 결제일시
            "payStatusType": "DONE", // 결제상태
            "payInfoJson": null, // 결제 정보 JSON
            "payInfo": {
                    "payType": "CREDIT_CARD", // 결제 유형
                    "cardInfo": {
                            "cardCompany": "SHINHAN", // 카드사
                            "cardCode": "CCLG", // PG 카드사 코드(PG별로 다름)
                            "cardName": "신한카드", // 카드사명
                            "approveYmdt": "2021-10-25 13:54:38", // 결제승인시간
                            "cardNo": "*****", // 카드번호
                            "cardApprovalNumber": "****", // 결제승인번호
                            "noInterest": true, // 무이자여부
                            "installmentPeriod": 5, // 할부기간
                            "cardAmt": 185000 // 신용카드 결제금액
                    },
                    "bankInfo": {
                            "bank" : "KDB", // 은행
                            "bankCode": "", // PG 은행코드 (PG별로 다름)
                            "bankName": "", // 은행명
                            "account": "", // 계좌번호
                            "bankAmt": 1000, // 입금해야할 금액
                            "depositAmt": 1000, // 실제 입금금액
                            "depositYmdt": "2021-10-25 13:54:38", // 입금일시
                            "remitterName": "", // 입금자명
                            "depositorName": "", // 예금주명
                            "paymentExpirationYmdt": "2021-10-25 13:54:38" // 입금 마감일
                    },
                    "cashAuthNo": "", // 현금영수증 승인번호
                    "cashNo": "", // 현금영수증 거래번호
                    "tradeNo": "3000000", // 거래번호
                    "escrowYn": "N", // 에스크로 결제 여부
                    "payAmt": 185000, // PG결제 금액
                    "sellerCouponAmt": 0, // 가맹점 발행쿠폰
                    "pgCouponAmt": 0, // PG 쿠폰 금액
                    "cardCouponAmt": 0, // 카드사 쿠폰 금액
                    "pointAmt": 0, // PG 포인트
                    "paymentKey": {
                            "pgType": "KCP", // PG 유형
                            "key": "key", // PG Key
                            "etcInfos": {} // 기타 결제 키 관련 정보
                    },
                    "taxType": "DUTY", // 과세유형 (과세,면세,영세)
                    "mobileInfo": { // 핸드폰 결제 정보
                    "mobileNo": "010-1234-5678", // 결제 핸드폰 번호
                    "mobileCompany": "" // 통신사
                    },
                    "naverPayInfo": { // 네이버 페이 결제 정보
                            "paymentMeans": "", // 네이버 페이 결제 수단
                            "paymentDueDate": "", // 입금 기한
                            "paymentNumber":"", // PG승인번호
                            "orderDiscountAmount": 1000, // 주문 할인액
                            "generalPaymentAmount": 1000, // 일반결제수단최종결제금액
                            "naverMileagePaymentAmount": 1000, // 네이버페이 포인트 최종 결제 금액
                            "chargeAmountPaymentAmount": 1000, // 충전금최종결제금액
                            "checkoutAccumulationPaymentAmount": 1000, // 네이버페이 적립금 최종 결제 금액
                            "orderType": "", // 주문 유형 구분(네이버페이/통합장바구니)
                            "payLocationType": "", // 결제 위치 구분(PC/MOBILE)
                            "paymentCoreType": "", // 결제 구분(네이버결제/PG 결제)
                            "payLaterPaymentAmount": 1000 // 후불결제 금액(네이버결제/PG 결제)
                    },
                    "recurringPaymentCycleDate": 15, // 정기결제 주기 일자
                    "rentalInfo": { // 렌탈 정보
                            "rentalPeriod": 1, // 렌탈 기간
                            "monthlyRentalAmount": 0.00, //월 렌탈료
                    },
                    "complexPayInfo": { // 복합결제 정보
                            "complexPayId": null, // 복합결제 키
                            "extraPayAmt": 0.00, // 추가 결제 금액
                            "mainPayAmt": 0.00, // 메인 결제 금액
                    }
            }
    }
}

2.2 주문상태변경

• 발행 시점 주문상태 변경이나 클레임 상태 변경 시

• '(2-1) 주문생성 웹훅'과 차이점

  • 주문상태 변경 웹훅은 주문단위가 아닌 주문상품 옵션단위로 처리됩니다.

Request Body

[{
    "eventType": "CHANGE_ORDER_STATUS", //이벤트명
    "orderProductOptionNo": 12345, // 주문상품 옵션번호
    "orderNo": "202110110111111", // 주문번호
    "memberNo": 12345, // 회원번호
    "userInputs": [  // 구매자 입력형 옵션
      {
        "inputLabel":"색깔", //구매자 작성형 옵션 이름
        "inputValue":"검정색", //구매자 입력형 옵션 값
      }
    ],
    "serviceNo": 12345, // 서비스번호
    "mallNo": 12345, // 몰번호
    "deliveryNo": 12345, // 배송번호
    "deliveryTemplateNo": 50000, // 배송 템플릿 번호
    "deliveryInternationalYn":false, // 해외배송여부
    "mallProductNo": 100000000, // 상품번호
    "productName": "상품명",
    "mallOptionNo": 6000000, // 상품옵션번호
    "optionUseYn": "Y", // 옵션 사용 여부
    "optionName": "옵션명",
    "optionValue": "옵션값",
    "imageUrl": "//rlyfaazj0.toastcdn.net/...", // 상품 이미지 url
    "orderCnt": 1, // 주문건수
    "originalOrderCnt": 1, // 최초 주문 수량
    "salePrice": 329000.00, // 판매 가격
    "immediateDiscountAmt": 144000.00, // 즉시 할인 가격
    "addPrice": 0.00, // 추가 금액
    "additionalDiscountAmt": 0.00, // 추가 할인 금액
    "partnerChargeAmt": 0.00, // 파트너 부담액
    "adjustedAmt": 185000.00, // 조정된 상품 금액
    "orderStatusType": "PAY_DONE", // 주문옵션상태
    "claimStatusType": null, // 클레임 상태
    "claimNo" : 12345, // 클레임 번호
    "orderYmdt": "2021-10-25 13:53:18", // 주문일시
    "payYmdt": "2021-10-25 13:54:38", // 결제일시
    "orderAcceptYmdt": null, // 주문접수일시
    "releaseReadyYmdt": null, // 배송준비일시
    "releaseYmdt": null, // 배송일시
    "deliveryCompleteYmdt": null, // 배송완료일시
    "buyConfirmYmdt": null, // 구매확정일시
    "registerYmdt": "2021-10-25 13:53:18", // 주문옵션 생성일시
    "trackingKey": "platform=MO&rid=851184319&aid=641_1_3_1025&mid=TMS", // 주문추적키 (쇼핑몰에서 생성되어 주문번호를 특정하는 구분값)
    "deliveryCompanyType": "CJ", // 배송 업체
    "invoiceNo": : "1212", // 송장번호
    "receiverName": "홍길동", // 받는 사람 이름
    "zipCd": 12345, // 배송지 우편 번호
    "address": "경기도 성남시 분당구 대왕판교로645번길 12", // 배송지 주소
    "detailAddress": "16 NHN 플레이뮤지엄", // 배송지 상세 주소
    "jibunAddress": "경기도 성남시 분당구 대왕판교로645번길", // 배송지 지번 주소
    "receiverCity": "", // 배송지 해외(도시)
    "receiverState": "", // 배송지 해외(주)
    "contact1": "010-0000-0000", // 수령자 연락처1
    "contact2": "", // 수령자 연락처2
    "productManagementCd": "", // 상품관리 코드
    "optionManagementCd": "", // 옵션관리 코드
    "usesShippingInfoLaterInput": false, // 나중배송지 입력 여부
    "shippingInfoLaterInputContact": null, // 나중배송지 입력 전화 번호
    "encryptedShippingNo": null, // 나중배송지 입력 시 사용하는 암호화된 배송번호
    "retrieveInvoiceUrl": null, // 배송조회 할 수 있는 url
    "isFreeGift": false, // 사은품 여부
    "updateAdminNo":0, // 수정한 어드민 번호
    "extraManagementCd":null, // 추가 관리 코드
    "order": {
        "extraData": null // 추가 정보
    }
}]

3. 어떻게 웹훅 사용요청 하나요?

1. 웹훅 사용정보 전달

워크스페이스> 셀러어드민 내 앱(APP) 등록을 통해 웹훅을 사용등록할 수 있습니다.

보다 자세한 내용은 앱등록 가이드를 참고하시길 바랍니다.

2. 웹훅 주의사항

샵바이 서버 또는 웹훅을 받는 서버의 문제로 일정 시간 웹훅이 통신되지 않을 경우

이미 발생했던 이벤트는 다시 전송되지 않습니다. 따라서 주문상태 조회 API와 함께 사용하시는 것을 권장합니다.

그 외 궁금하신 사항/어려움이 있다면 아래 코멘트를 남겨주세요~ 포럼 운영자가 아니더라도 누구나 서로에게 답변할 수 있습니다. shopby에서 제공하는 웹훅에 대해 추가적인 문의 또는 제안사항을 코멘트로 남겨주시면 워크스페이스 운영에 더욱 도움이 될 거예요!