[고도몰] 웹훅(webhook) 가이드

고도몰에서 제공되는 다양한 웹훅 가이드를 안내 드립니다.

목차

• 이해하기

• 웹훅의 장점

• 웹훅 사용 사례

• 제공 이벤트 항목

• 이벤트별 샘플 데이터와 코드 정의

  • 1. 앱 관련

  • 2. 회원 관련

  • 3. 상품 관련

  • 4. 주문 관련

---

이해하기

• 웹훅이란 서버에서 특정 이벤트 발생했을 때 다른 서비스나 응용프로그램으로 알림을 보내는 기능입니다.

• 이를 사용하면 특정 이벤트가 발생한 시점에 지정한 callback URL로 이벤트 정보를 수신할 수 있습니다.

• 주기적으로 데이터를 조회하지 않고 원하는 이벤트에 대한 정보만 수신할 수 있어서 웹훅은 리소스나 통신 측면에서 효율적입니다.

---

웹훅의 장점

• 웹훅의 가장 큰 장점은 원하는 이벤트가 발생했을 때만 데이터를 수신하여 효율적으로 데이터 통신을 할 수 있다는 점입니다.

• 이를 통해 서버와 클라이언트 간의 불필요한 통신을 줄이고, 서버의 부하를 최소화할 수 있습니다.

• 또한, 웹훅은 비동기적으로 작동하여 이벤트가 즉시 처리되므로 실시간에 가까운 정보 업데이트가 가능합니다. 이는 빠른 응답 시간이 필요한 애플리케이션에 특히 유리합니다.

---

웹훅 사용 사례

• 알림 시스템: 결제 시스템에서 구매가 완료되었을 때, 사용자에게 이메일이나 문자로 알림을 보내는 경우.

• 데이터 동기화: 여러 서비스 간의 데이터 일치를 유지하기 위해 이벤트 발생 시 자동으로 업데이트하는 경우.

• 자동화 작업: 빌드시스템에서 코드 변경 시 자동으로 테스트 및 배포를 실행하는 경우.

위와 같은 사례들은 웹훅의 효율성을 잘 보여주며 다양한 분야에서 활용될 수 있습니다.

웹훅을 통해 우리는 이벤트 기반 자동화 모델을 구축할 수 있습니다. 이러한 자동화는 개발자의 개입을 최소화하고 시스템의 유지 보수를 용이하게 합니다. 충분한 유연성과 적응성을 제공하는 웹훅은 다양한 언어와 플랫폼에서 쉽게 통합될 수 있으며, 이는 개발 주기를 가속화시킵니다. 활용 가능한 API와 결합하면, 무한한 기능 확장이 가능하여 더욱 풍부한 사용자 경험을 제공할 수 있습니다.

웹훅 이벤트는 앱이 설치된 쇼핑몰에서 발생하는 이벤트 정보를 수신할 수 있으며,

장애가 발생하여 발생한 이벤트에 대해 웹훅(Webhook)을 수신하지 못하는 경우 웹훅이 재 전송되지 않습니다.

단, 수신하지 못한 웹훅은 실패한 웹훅 조회하기 API로 조회할 수 있습니다.

그렇다면 고도몰에서는 어떠한 이벤트 항목의 웹훅을 제공하고 있을까요?

---

제공 이벤트 항목

이벤트 유형	이벤트명
CHANGE_APP_STATUS	앱 설치/삭제
GD_MEMBER_LOGGED_IN	회원 로그인
GD_MEMBER_CREATED	회원 가입 완료
GD_MEMBER_GRADE_CHANGED	회원 등급 변경
GD_MEMBER_INFO_CHANGED	회원 정보 수정
GD_MEMBER_WITHDRAW	회원 탈퇴
GD_PRODUCT_UPDATED	상품 등록/수정/삭제
GD_ORDER_COMPLETED	결제 완료
GD_ORDER_CREATED	입금대기 주문 생성
GD_ORDER_GOODS_STATUS_CHANGED	주문 상품 상태 변경 (주문취소)

---

이벤트별 샘플 데이터와 코드 정의

1. 앱 관련

이벤트 유형	이벤트명
CHANGE_APP_STATUS	앱 설치/삭제

// 샘플 데이터 및 파라미터 정의
{
        "eventType": "CHANGE_APP_STATUS", // not null
        "currentStatus": {앱설치상태}, // ("ACTIVE" || "DELETED")
        "appNo": {앱번호}, // not null
        "appInstalledNo": {앱설치번호}, // not null
        "mallNo": {샵바이 쇼핑몰번호}, // not null
        "shopNo": {샵바이/고도몰 상점번호}, // not null
        "solutionType": {솔루션 구분}, // not null, ("SHOPBY" || "GODO")
}

---

2. 회원 관련

[회원 로그인]

이벤트 유형	이벤트명
GD_MEMBER_LOGGED_IN	회원 로그인

// 샘플 데이터 및 파라미터 정의
{
        "eventType": "GD_MEMBER_LOGGED_IN", // not null
        "shopNo": 상점번호, // not null
        "trackingKey": "트래킹키", // nullable
        "memberNo": 회원번호, // not null
        "memberId": "회원아이디", // not null
}

---

[회원 가입 완료, 회원 등급 변경, 회원 정보 수정, 회원 탈퇴]

이벤트 유형	이벤트명
GD_MEMBER_CREATED	회원 가입 완료
GD_MEMBER_GRADE_CHANGED	회원 등급 변경
GD_MEMBER_INFO_CHANGED	회원 정보 수정
GD_MEMBER_WITHDRAW	회원 탈퇴

// 샘플 데이터 및 파라미터 정의
{
        "eventType": 이벤트유형,  // not null
        "shopNo": 상점번호, // not null
        "trackingKey": "트래킹키", // nullable
        "memberNo": 회원번호,  // not null
        "memberId": "회원아이디",  // not null
        "memberName": "회원이름",  // not null
        "email": "이메일", // nullable
        "groupNo": "회원그룹번호", // not null
        "nickName": "닉네임", // nullable
}

---

3. 상품 관련

이벤트 유형	이벤트명
GD_PRODUCT_UPDATED	상품 등록/수정/삭제

// 샘플 데이터 및 파라미터 정의
{
        "eventType": "GD_PRODUCT_UPDATED", // not null
        "shopNo": 상점번호, // not null
        "trackingKey": "트래킹키", // nullable
        "goodsNo": 상품번호, // not null (여러개인경우 ,로 연결)
        "goodsEventType": "이벤트타입", // not null, ("CREATED" || "UPDATED" || "DELETED")
        "timestamp": "발생일시" // not null
}

---

4. 주문 관련

[결제 완료, 입금 대기 주문 생성]

이벤트 유형	이벤트명
GD_ORDER_COMPLETED	결제 완료
GD_ORDER_CREATED	입금대기 주문 생성

// 샘플 데이터 및 파라미터 정의
{
        "eventType": "GD_ORDER_COMPLETED", // not null
        "shopNo": 상점번호, // not null
        "trackingKey": "트래킹키", // nullable
        "orderNo": 주문번호, // not null
        "memberNo": 회원번호, // not null
        "totalSettlePrice": 총 결제금액, // not null
        "orderTypeFl" : 주문 유형 // not null ("pc" || "mobile" || "write")
        "appOs" :  앱 주문시 휴대폰 OS // nullable ("ios" || "android" || "etc")
        "channelType" :  주문건 추적 채널타입 데이터// nullable: true
        "refererUrl" : 주문 생성 시점에 접속된 URL // not null
        "orderCustomerName" : 주문자명, // not null
        "orderDate" : 주문일자, // not null
        "orderCustomerPhone" : 주문자 핸드폰 번호 , // nullable
        "orderCustomerEmail" : 주문자 이메일, // nullable
        "depositorName" : 입금자명, // nullable
        "depositDeadline" : 입금 마감일, // nullable
        "taxReceiptType": 현금영수증/세금계산서 유형, // nullable("CASH_RECEIPT" || "TAX_INVOICE")
        "cashReceiptType": 현금 영수증 발행 용도, // nullable("EXPENSE_PROOF" || "INCOME_DEDUCTION")
        "authenticationCode": 인증번호 // nullable
}

---

[주문 상품 상태 변경]

• 기존 주문 건의 상태 변경에 대한 웹훅으로 신규 생성된 주문 건에 대해서는 웹훅 발행되지 않습니다.

• [기본설정 > 주문정책 > 주문상태설정] 에서 추가한 커스텀 주문 상태로 변경된 경우 웹훅 발행되지 않습니다.

• 웹훅은 동일한 주문 번호에 묶여있는 모든 상품(주문 상품 번호)의 정보가 포함되어 전송됩니다. 단, 송장일괄등록으로 배송 상태가 변경되거나, 클레임 처리(교환/환불/반품) 상품의 상태가 변경될 경우 주문 상품 번호 단위로 개별 발행 됩니다.

이벤트 유형	이벤트명
GD_ORDER_GOODS_STATUS_CHANGED	주문 상품 상태 변경

// 샘플 데이터 및 파라미터 정의
[
    {
        "eventType": "GD_ORDER_GOODS_STATUS_CHANGED", // not null
        "shopNo": 상점번호, // not nul 
        "orderNo": 주문 번호, // not null
        "orderGoodsNo": 주문 상품 번호, // not null,
        "orderGoodsStatus": "주문 상품 상태", // not null
        "statusChangeDateTime": "주문 상품 상태 변경일", // not null
    }
]

---

[참고] 주문 상품 상태 코드값

입금대기	ORDER
결제완료	PAYMENT
상품준비중	GOODS_READY
구매발주	GOODS_PLACEMENT
상품입고	GOODS_RECEIVED
상품출고	GOODS_SHIPPED
배송중	DELIVERY
배송완료	DELIVERY_COMPLETE
구매확정	SETTLE
자동취소	CANCEL_AUTO
품절취소	CANCEL_OUT_OF_STOCK
관리자취소	CANCEL_ADMIN
고객취소요청	CANCEL_CUSTOMER_REQUEST
반품접수	BACK_REQUEST
반송중 (반품)	BACK_IN_TRANSIT
반품보류	BACK_ON_HOLD
반품회수완료	BACK_COMPLETE
교환접수	EXCHANGE_REQUEST
반송중 (교환)	EXCHANGE_IN_TRANSIT
재배송중	EXCHANGE_REDELIVERY
교환보류	EXCHANGE_ON_HOLD
교환완료	EXCHANGE_COMPLETE
환불접수	REFUND_REQUEST
환불보류	REFUND_ON_HOLD
환불완료	REFUND_COMPLETE

---