[샵바이] 웹훅(webhook) 가이드
샵바이에서 제공되는 다양한 웹훅 가이드를 안내 드립니다.
목차
이해하기
웹훅(Webhook)이란 서버에서 특정 이벤트 발생했을 때 다른 서비스나 응용프로그램으로 알림을 보내는 기능입니다.
이를 사용하면 특정 이벤트가 발생했을 때 지정한 callback URL로 관련 이벤트 정보를 수신할 수 있습니다.
주기적으로 데이터를 조회하지 않고 원하는 이벤트에 대한 정보만 수신할 수 있어서 webhook은 리소스나 통신 측면에서 효율적입니다.
어떠한 이벤트가 발생했을 때 정보를 수신할 수 있는지는 제공 이벤트 항목 내용을 참고해 주시기 바랍니다.
웹훅 이벤트는 앱이 설치된 쇼핑몰에서 발생하는 이벤트 정보를 수신할 수 있으며, 장애가 발생하여 발생한 이벤트에 대해 웹훅(Webhook)을 수신하지 못하는 경우 웹훅이 재 전송되지 않습니다. 단, 수신하지 못한 웹훅은 실패한 웹훅 조회하기 API로 조회할 수 있습니다.
웹훅(Webhook) 설정 방법
워크스페이스>셀러어드민에서 앱 등록/수정 시 개발 정보 탭에서 설정할 수 있습니다. 지원 가능한 method : POST / PUT
워크스페이스에 로그인하여 셀러어드민>상품>앱>[T]개발 정보 화면에 접속합니다.
사용할 웹훅(Webhook) 이벤트를 사용함으로 설정합니다.
method 및 이벤트 발생 시 웹훅(Webhook)을 수신할 URL을 설정합니다.
설정된 내용을 [저장] 합니다.
웹훅 설정 이후 앱이 쇼핑몰에 설치되어야 이벤트 정보를 수신할 수 있습니다.
웹훅(Webhook)을 설정할 때는 관련된 server API의 권한이 있는 이벤트 항목만 사용할 수 있으며,
보유한 server API 권한을 삭제할 때는 관련 이벤트 항목의 웹훅(Webhook) 설정도 '사용 안 함'으로 설정해 주셔야 합니다.
판매앱의 정보를 변경하는 경우 심사 요청 후 심사가 승인되어야 변경된 정보가 반영됩니다.
제공 이벤트 항목
이벤트별 샘플 데이터와 코드 정의
1. 앱 관련
// 샘플 데이터 및 파라미터 정의
{
"eventType": "CHANGE_APP_STATUS", // 이벤트명
"currentStatus": "ACTIVE", // 앱상태
"appNo": 12345, // 앱일련번호
"mallNo": 12345, // 쇼핑몰번호
"appInstalledNo": 12345, // 앱설치번호
}2. 전시 관련
// 샘플 데이터 및 파라미터 정의
{
"eventType": "PRODUCT_INQUIRY_ADDED", //이벤트명
"mallNo": 12345, //쇼핑몰번호
"inquiryNo" : 12345 //상품문의번호
}3. 운영 관련
[적립금]
// 샘플 데이터 및 파라미터 정의
{
"eventType": "ACCUMULATION_ADDED", //이벤트명
"mallNo": 12345, //쇼핑몰번호
"memberNo": 135375046, //회원번호
"amount": 1000, //적립 또는 차감금액
"accumulationReserveReason": "ADD_MANUAL", // 적립 또는 차감 사유
"reasonDetail": "테스트 지급", // 상세
"orderNo": null, //주문번호
"orderOptionNo": "0", //주문옵션번호
"registerAdminNo": 4099, //운영자번호
"reviewNo": null //상품후기번호
}[1:1문의]
// 샘플 데이터 및 파라미터 정의
{
"eventType": "INQUIRY_ADDED", //이벤트명
"mallNo": 12345, //쇼핑몰번호
"memberNo": 12345, //회원번호
"inquiryNo": 12345, //1:1문의 일련번호
"inquiryTypeNo": 12345, //1:1문의 유형번호
"orderNo": null, // 주문에 대한 문의인 경우 주문번호
"productNo": null, //주문된 상품번호
"answerSmsSendYn": true, //1:1문의 답변 등록 시 SMS수신여부
"inquiryTitle": "타이틀", //1:1문의 제목
"memberId": "12345@nhn-commerce.com"//회원이메일
}4. 회원 관련
// 샘플 데이터 및 파라미터 정의
{
"eventType": "MEMBER_CREATED", //이벤트명
"mallNo": 12345, //쇼핑몰 번호
"memberNo": 12345, //회원번호
"memberId": "chulsu", //회원아이디(외부연동 ID로 가입 시 null)
"memberName": "홍길동", //회원이름
"email": "gildong@nhn-commerce.com", //회원이메일
"providerType": "KAKAO", //외부연동 ID로 가입 시 외부연동 값 노출(KAKAO, PAYCO 등),
"gradeNo": 12345, //등급번호(회원의 등급이 변경된 경우 변경된 등급의 등급번호)
"nickName": "angel1004" //닉네임
}5. 주문 관련
[주문 생성]
// 샘플 데이터 및 파라미터 정의
{
"eventType": "CREATE_ORDER", //이벤트명
"order": {
"orderNo": "2021100201234567890", // 주문번호
"mallNo": 30973, // 몰번호
"serviceNo": 30388, // 서비스 번호
"memberNo": 8411244, // 회원번호
"memberYn": "Y", // 회원여부
"ordererName": "홍길동", // 주문자명
"ordererContact1": "010-1234-1234", // 주문자 핸드폰 번호
"ordererContact2": "010-1234-1234", // 주문자 전화 번호
"ordererEmail": "honggildong@naver.com", // 주문자 이메일
"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, // 장바구니쿠폰 발급 번호
"orderProducts": [
{
"orderProductNo": 50000000, // 주문상품번호
"mallProductNo": 100000000, // 상품번호
"productName": "상품명",
"productManagementCd": "", // 상품관리 코드
"hsCode": "",
"eanCode": null,
"partnerNo": 50000, // 파트너 번호
"lastProductCouponDiscountAmt": 0.00, // 상품 쿠폰 할인액
"productCouponIssueNo": 13, // 사용한 상품 쿠폰 번호
"orderProductOptions": [
{
"orderProductOptionNo": 5062925, // 주문상품옵션번호
"orderNo": "2021100201234567890", // 주문번호
"memberNo": 100000, // 회원번호
"userInputs": [ // 구매자 입력형 옵션
{
"inputLabel": "색깔", // 구매자 작성형 옵션 이름
"inputValue":"검정색", //구매자 입력형 옵션 값
}
],
"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, // 배송번호
"deliveryInternationalYn": false, // 해외배송여부
"optionManagementCd": "", // 옵션 관리 코드
"deliveryTemplateNo": 50000, // 배송 템플릿 번호
"deliveryCompanyType": "CJ", // 배송 업체
"invoiceNo": null, // 송장번호
"receiverName": "홍길동", // 받는 사람 이름
"receiverContact1": "010-1234-5678", //수령자 휴대폰번호
"receiverContact2": "", //수령자 전화번호
"zipCd": 12345, //배송지 우편번호
"receiverAddress": "", // 주소
"receiverDetailAddress": "", // 상세 주소
"receiverJibunAddress": "", //지번 주소
"usesShippingInfoLaterInput": false, // 나중배송지 입력 여부
"shippingInfoLaterInputContact": null, // 나중배송지 입력 전화 번호
"encryptedShippingNo": null, // 나중배송지 입력 시 사용하는 암호화된 배송번호
"shippingEmptyAutoCancelYmdt" : "2023-10-25 13:54:38", // 배송지 미입력 시 자동 주문취소 일시
"customsIdNumber": '', // 개인통관고유부호
}
]
}
]
},
"pay": {
"pgType": "KCP", // PG 타입
"payType": "CREDIT_CARD", // 결제 유형
"payYmdt": "2021-10-25 13:54:38", // 결제일시
"payStatusType": "DONE", // 결제상태
"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 결제)
}
}
}
}[주문상태변경]
// 샘플 데이터 및 파라미터 정의
[
{
"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, // 클레임 상태
"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
}
][수령자 정보 변경]
// 샘플 데이터 및 파라미터 정의
{
"eventType": "UPDATE_RECEIVER", // 이벤트 명
"mallNo": 12345, // 쇼핑몰 번호
"orderNo": "", // 주문 번호
"shippings": [
// 배송정보
{
shippingNo": 0, // 배송번호
customsIdNumber": '', // 개인통관고유부호
receiverAddress": {
// 수령자 정보
"zipCd": 12345, // 배송지 우편 번호
"address": "경기도 성남시 분당구 대왕판교로645번길 12", // 배송지 주소
"detailAddress": "16 NHN 플레이뮤지엄", // 배송지 상세 주소
"jibunAddress": "경기도 성남시 분당구 대왕판교로645번길", // 배송지 지번 주소
"receiverCity": "", // 배송지 해외(도시)
"receiverState": "", // 배송지 해외(주)
"contact1": "010-0000-0000", // 수령자 연락처1
"contact2": "", // 수령자 연락처2
"name": "홍길동", // 수령자 이름
"shippingEtcInfo": {
// 해외배송지 기타정보
"receiverFirstName": "", // 수령자 FirstName
"receiverLastName": "", // 수령자 LastName
"orderAdditionalInfo": "", // 주문 추가 정보
},
},
"countryCd": "", // 국가 코드
"memo": "", // 배송 메모
}
]
}[업무메시지]
// 샘플 데이터 및 파라미터 정의
{
"eventType": "ADD_TASK_MESSAGE", // 이벤트명
"content": "content", // 이벤트시 작성된 내용
"isDetail": true, // 상세 메시지 여부
"taskMessage": {
// 업무메시지 정보
"taskMessageNo": 0, // 업무메시지 번호
"taskMessageChannelType": "PARTNER", // 메시지 작성 채널
"taskMessageStatusType": "PROCESSING", // 진행 상황
"taskMessageType": "PAY", // 업무메시지 유형
"fromTargetType": "PARTNER", // 발송자 타입
"fromTargetNo": 0, // 발송자 번호
"toTargetType": "PARTNER", // 담당자 타입
"toTargetNo": 0, // 담당자 번호
"content": "content", // 업무메시지 내용
"orderNo": 0, // 주문 번호
"orderProductOptionNo": 0, // 주문 옵션 번호
"productName": "product-name", // 상품 명 (nullable)
"registerYmdt": "2023-02-21 13:32:47", // 등록일시
"updateYmdt": "2023-02-21 13:32:47", // 수정일시 (nullable)
"completeYmdt": "2023-02-21 13:32:47", // 완료일시 (완료되지 않은 경우: null)
"taskMessageDetails": [
// 상세 메시지 정보
{
"taskMessageDetailNo": 0, // 업무메시지 상세 번호
"taskMessageChannelType": "PARTNER", // 상세 메시지 작성 채널
"content": "content", // 업무메시지 상세 내용
"registerYmdt": "2023-02-21 13:32:47", // 등록일시
"updateYmdt": "2023-02-21 13:32:47", // 수정일시 (nullable)
}
]
}
}6. 상품 관련
// 샘플 데이터 및 파라미터 정의
{
"eventType": "PRODUCT_UPDATED", // 이벤트 유형
"mallNo": 12345, // 쇼핑몰번호
"productEventType": "CREATED" || "UPDATED" || "DELETED", // 등록 또는 수정 또는 삭제
"mallProductNos": [1000,20000], //상품번호
}Last updated