웹훅(Webhook)이란 서버에서 특정 이벤트 발생했을 때 다른 서비스나 응용프로그램으로 알림을 보내는 기능입니다.
이를 사용하면 특정 이벤트가 발생했을 때 지정한 callback URL로 관련 이벤트 정보를 수신할 수 있습니다.
주기적으로 데이터를 조회하지 않고 원하는 이벤트에 대한 정보만 수신할 수 있어서 webhook은 리소스나 통신 측면에서 효율적입니다.
어떠한 이벤트가 발생했을 때 정보를 수신할 수 있는지는 제공 이벤트 항목 내용을 참고해 주시기 바랍니다.
웹훅 이벤트는 앱이 설치된 쇼핑몰에서 발생하는 이벤트 정보를 수신할 수 있으며,
장애가 발생하여 발생한 이벤트에 대해 웹훅(Webhook)을 수신하지 못하는 경우 웹훅이 재 전송되지 않습니다.
단, 수신하지 못한 웹훅은 실패한 웹훅 조회하기 API로 조회할 수 있습니다.
웹훅(Webhook) 설정 방법
워크스페이스>셀러어드민에서 앱 등록/수정 시 개발 정보 탭에서 설정할 수 있습니다.
지원 가능한 method : POST / PUT
워크스페이스에 로그인하여 셀러어드민>상품>앱>[T]개발 정보 화면에 접속합니다.
사용할 웹훅(Webhook) 이벤트를 사용함으로 설정합니다.
method 및 이벤트 발생 시 웹훅(Webhook)을 수신할 URL을 설정합니다.
설정된 내용을 [저장] 합니다.
웹훅 설정 이후 앱이 쇼핑몰에 설치되어야 이벤트 정보를 수신할 수 있습니다.
웹훅(Webhook)을 설정할 때는 관련된 server API의 권한이 있는 이벤트 항목만 사용할 수 있으며,
보유한 server API 권한을 삭제할 때는 관련 이벤트 항목의 웹훅(Webhook) 설정도 '사용 안 함'으로 설정해 주셔야 합니다.
// 샘플 데이터 및 파라미터 정의
{
"eventType": "CHANGE_APP_STATUS", // 이벤트명
"currentStatus": "ACTIVE", // 앱상태
"appNo": 12345, // 앱일련번호
"mallNo": 12345, // 쇼핑몰번호
"appInstalledNo": 12345, // 앱설치번호
}
// 샘플 데이터 및 파라미터 정의
{
"eventType": "PRODUCT_INQUIRY_ADDED", //이벤트명
"mallNo": 12345, //쇼핑몰번호
"inquiryNo" : 12345 //상품문의번호
}
// 샘플 데이터 및 파라미터 정의
{
"eventType": "PRODUCT_REVIEW_ADDED", //이벤트명
"mallNo": 12345, //쇼핑몰번호
"reviewNo" : 12345 //쇼핑몰에서 등록된 상품후기의 상품리뷰번호
"reviewNos": [12345, 12346] //server API로 등록된 상품후기의 상품리뷰번호
}
// 샘플 데이터 및 파라미터 정의
{
"eventType": "ACCUMULATION_ADDED", //이벤트명
"mallNo": 12345, //쇼핑몰번호
"memberNo": 135375046, //회원번호
"amount": 1000, //적립 또는 차감금액
"accumulationReserveReason": "ADD_MANUAL", // 적립 또는 차감 사유
"reasonDetail": "테스트 지급", // 상세
"orderNo": null, //주문번호
"orderOptionNo": "0", //주문옵션번호
"registerAdminNo": 4099, //운영자번호
"reviewNo": null //상품후기번호
}
// 샘플 데이터 및 파라미터 정의
{
"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": "[email protected]"//회원이메일
}
// 샘플 데이터 및 파라미터 정의
{
"eventType": "MEMBER_CREATED", //이벤트명
"mallNo": 12345, //쇼핑몰 번호
"memberNo": 12345, //회원번호
"memberId": "chulsu", //회원아이디(외부연동 ID로 가입 시 null)
"memberName": "홍길동", //회원이름
"email": "[email protected]", //회원이메일
"providerType": "KAKAO", //외부연동 ID로 가입 시 외부연동 값 노출(KAKAO, PAYCO 등)
"gradeNo": 12345, //등급번호(회원의 등급이 변경된 경우 변경된 등급의 등급번호)
"groupNos": [1, 2, 3], // 그룹번호 리스트(회원의 그룹이 추가/삭제된 경우, 반영이 된 모든 그룹번호 목록)
"nickName": "angel1004", //닉네임
"representativeMemberNo": 12345 //대표몰 회원번호(브랜드 로그인 사용하지 않는 경우 null)
}
// 샘플 데이터 및 파라미터 정의
[
{
"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, // 상품옵션번호
"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", // 주문추적키 (쇼핑몰에서 생성되어 주문번호를 특정하는 구분값)
"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": "", // 옵션의 추가관리코드 (상품 등록/수정에서 설정 가능)
"order": {
"extraData": "{"language": "KO"}",
"currencyCode": "KRW",
"exchangeRate": null
},
"claimNo": 123,
"requestChannelType": "USER" // 상태변경이 요청된 채널 [SYSTEM, SERVICE, PARTNER, BATCH, USER, SERVER]
"channelType": null // 유입 경로
}
]
// 샘플 데이터 및 파라미터 정의
{
"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)
}
]
}
}
// 샘플 데이터 및 파라미터 정의
{
"eventType": "PRODUCT_UPDATED", // 이벤트 유형
"mallNo": 12345, // 쇼핑몰번호
"productEventType": "CREATED" || "UPDATED" || "DELETED", // 등록 또는 수정 또는 삭제
"mallProductNos": [1000,20000], //상품번호
}
// 샘플 데이터 및 파라미터 정의
{
"eventType": "COUPON_ADDED",
"mallNo": 12345, // 쇼핑몰번호,
"coupons": [
{
"couponNo": 11111, // 쿠폰번호
"couponName": "쿠폰명",
"couponIssueType": "DOWNLOAD", // 발급 유형 : 다운로드 발급 / 코드 발급(직접입력) / 코드 발급(자동생성) / 자동 발급
"couponStatusType": "ISSUE_ING", // 발급 상태 : 발급대기 / 발급중 / 발급중지 / 발급종료
"couponType": "CART" // 혜택 구분 : 상품적용 쿠폰 / 주문적용 쿠폰 / 기프트 쿠폰
}
]
}
