[고도몰] 웹훅(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_MEMBER_MILEAGE_CHANGED	회원 마일리지 변경
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
}

---

[회원 마일리지]

이벤트 유형	이벤트명
GD_MEMBER_MILEAGE_CHANGED	회원 마일리지 변경 (마일리지 적립, 소멸, 차감 시 발행)

// 샘플 데이터 및 파라미터 정의
{
      "eventType": "GD_MEMBER_MILEAGE_CHANGED",  // not null
      "shopNo": "상점번호", // not nul 
      "sno": "마일리지 번호", // not null
      "memberSno": 회원 번호 // not null
      "mileageEventType": "마일리지이벤트 유형", // not null("EARN" || "EXPIRE" || DEDUCT)
      "mileage": "변경 마일리지", // not null
      "afterMileage": "변경후 최종 마일리지", // not null
      "mileageChangeDateTime": "마일리지 변경 일시", // not null
      "expirationDateTime": "마일리지 소멸 일시", // nullable
      "trackingKey": "트래킹키" // 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
        "paymentMethod": "결제수단" // 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

---

[참고] 결제 수단 코드값

에스크로 계좌이체	EB
에스크로 신용카드	EC
에스크로 가상계좌	EV
간편결제 계좌이체	FB
간편결제 신용카드	FC
간편결제 휴대폰	FH
간편결제 포인트	FP
간편결제 가상계좌	FV
간편결제 무통장입금	FA
무통장 입금	GB
PAYPAL	OP
VISA / MASTER	OV
JCB / AMEX	OJ
ALIPAY	OA
TENPAY	OT
UNIONPAY	OU
계좌이체	PB
신용카드	PC
휴대폰	PH
가상계좌	PV
간편결제 카카오페이	PK
간편결제 후불결제	PL
간편결제 네이버페이	PN
토스페이	PT
페이코	PP
예치금	GD
마일리지	GM
전액할인	GZ
기타	GR