> For the complete documentation index, see [llms.txt](https://workspace-help.nhn-commerce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://workspace-help.nhn-commerce.com/app-guide/godomall_webhook.md).

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

## 목차

* [#undefined-1](#undefined-1 "mention")
* [#undefined-2](#undefined-2 "mention")
* [#undefined-3](#undefined-3 "mention")
* [#undefined-4](#undefined-4 "mention")
* [#undefined-5](#undefined-5 "mention")
  * [#id-1](#id-1 "mention")
  * [#id-2](#id-2 "mention")
  * [#id-3](#id-3 "mention")
  * [#id-4](#id-4 "mention")
  * [#id-5](#id-5 "mention")

***

## 이해하기

* 웹훅이란 서버에서 특정 이벤트 발생했을 때 다른 서비스나 응용프로그램으로 알림을 보내는 기능입니다.
* 이를 사용하면 특정 이벤트가 발생한 시점에 지정한 callback URL로 이벤트 정보를 수신할 수 있습니다.
* 주기적으로 데이터를 조회하지 않고 원하는 이벤트에 대한 정보만 수신할 수 있어서 웹훅은 리소스나 통신 측면에서 효율적입니다.

***

## 웹훅의 장점

* 웹훅의 가장 큰 장점은 원하는 이벤트가 발생했을 때만 데이터를 수신하여 효율적으로 데이터 통신을 할 수 있다는 점입니다.
* 이를 통해 서버와 클라이언트 간의 불필요한 통신을 줄이고, 서버의 부하를 최소화할 수 있습니다.
* 또한, 웹훅은 비동기적으로 작동하여 이벤트가 즉시 처리되므로 실시간에 가까운 정보 업데이트가 가능합니다.\
  이는 빠른 응답 시간이 필요한 애플리케이션에 특히 유리합니다.

***

## 웹훅 사용 사례

* **알림 시스템**: 결제 시스템에서 구매가 완료되었을 때, 사용자에게 이메일이나 문자로 알림을 보내는 경우.
* **데이터 동기화:** 여러 서비스 간의 데이터 일치를 유지하기 위해 이벤트 발생 시 자동으로 업데이트하는 경우.
* **자동화 작업**: 빌드시스템에서 코드 변경 시 자동으로 테스트 및 배포를 실행하는 경우.

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

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

{% hint style="warning" %}
웹훅 이벤트는 <mark style="color:red;">앱이 설치된 쇼핑몰에서 발생하는 이벤트 정보를 수신</mark>할 수 있으며,

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

단, 수신하지 못한 웹훅은 [실패한 웹훅 조회하기 API](https://server-docs.godomall.com/?activeName=%EC%9D%B8%EC%A6%9D#/Webhook/get-webhooks-failed)로 조회할 수 있습니다.
{% endhint %}

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

***

### 제공 이벤트 항목

| 이벤트 유형                            | 이벤트명               |
| --------------------------------- | ------------------ |
| 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 | 주문 상품 상태 변경        |
| GD\_CART\_UPDATED                 | 회원 장바구니 등록(비회원 제외) |

***

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

### 1. 앱 관련

<table><thead><tr><th>이벤트 유형</th><th>이벤트명</th><th data-hidden></th></tr></thead><tbody><tr><td>CHANGE_APP_STATUS</td><td>앱 설치/삭제</td><td></td></tr></tbody></table>

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

***

### 2. 회원 관련

#### <mark style="color:red;">\[회원 로그인]</mark>

| 이벤트 유형                 | 이벤트명   |
| ---------------------- | ------ |
| GD\_MEMBER\_LOGGED\_IN | 회원 로그인 |

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

***

#### <mark style="color:red;">\[회원 가입 완료, 회원 등급 변경, 회원 정보 수정, 회원 탈퇴]</mark>

| 이벤트 유형                     | 이벤트명     |
| -------------------------- | -------- |
| GD\_MEMBER\_CREATED        | 회원 가입 완료 |
| GD\_MEMBER\_GRADE\_CHANGED | 회원 등급 변경 |
| GD\_MEMBER\_INFO\_CHANGED  | 회원 정보 수정 |
| GD\_MEMBER\_WITHDRAW       | 회원 탈퇴    |

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

***

#### <mark style="color:red;">\[회원 마일리지]</mark>

| 이벤트 유형                       | 이벤트명                                         |
| ---------------------------- | -------------------------------------------- |
| GD\_MEMBER\_MILEAGE\_CHANGED | <p>회원 마일리지 변경<br>(마일리지  적립, 소멸, 차감 시 발행)</p> |

```java
// 샘플 데이터 및 파라미터 정의
{
      "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 | 상품 등록/수정/삭제 |

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

***

### 4. 주문 관련

#### <mark style="color:red;">\[결제 완료, 입금 대기 주문 생성]</mark>

| 이벤트 유형               | 이벤트명       |
| -------------------- | ---------- |
| GD\_ORDER\_COMPLETED | 결제 완료      |
| GD\_ORDER\_CREATED   | 입금대기 주문 생성 |

```java
// 샘플 데이터 및 파라미터 정의
{
        "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
}
```

***

#### <mark style="color:red;">\[주문 상품 상태 변경]</mark>

* 기존 주문 건의 상태 변경에 대한 웹훅으로 신규 생성된 주문 건에 대해서는 웹훅 발행되지 않습니다.
* \[기본설정 > 주문정책 > 주문상태설정] 에서 추가한 커스텀 주문 상태로 변경된 경우 웹훅 발행되지 않습니다.
* 웹훅은 동일한 주문 번호에 묶여있는 모든 상품(주문 상품 번호)의 정보가 포함되어 전송됩니다.\
  단, 송장일괄등록으로 배송 상태가 변경되거나, 클레임 처리(교환/환불/반품) 상품의 상태가 변경될 경우 주문 상품 번호 단위로 개별 발행 됩니다.&#x20;

| 이벤트 유형                            | 이벤트명        |
| --------------------------------- | ----------- |
| GD\_ORDER\_GOODS\_STATUS\_CHANGED | 주문 상품 상태 변경 |

```java
// 샘플 데이터 및 파라미터 정의
[
    {
        "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
    }
]
```

***

### 5. 장바구니 관련

| 이벤트 유형            | 이벤트명                |
| ----------------- | ------------------- |
| GD\_CART\_UPDATED | 회원 장바구니 등록(비회원  제외) |

```java
// 샘플 데이터 및 파라미터 정의
{
        "eventType": "GD_CART_UPDATED", // not null,
        "shopNo": 상점번호, // not null,
        "actionType": 처리유형, // not null,
        "memberNo" : 회원번호 // not null,
        "goodsNo" : 상품번호 // not null,
        "goodsCnt" : 구매수량 // not null,
        "goodsOptionNo" : 상품 옵션 번호
        "goodsOptionText" :
        [
            {
                "goodsOptionTextNo" : 상품 텍스트 옵션 번호,
                "value" : 상품 텍스트 옵션 내용
            },
        ],
        "addGoods" :
        [
            {
                "addGoodsNo" : 추가상품 번호,
                "addGoodsCnt" : 추가상품 갯수
            },
        ],
        "updatedDateTime" : "처리 시간"
        "trackingKey": "트래킹키"
}
```

***

#### <mark style="color:$info;">\[참고] 주문 상품 상태 코드값</mark>

<table data-header-hidden><thead><tr><th width="372.181884765625">주문 상태</th><th>주문 상태 웹훅값</th></tr></thead><tbody><tr><td>입금대기</td><td>ORDER</td></tr><tr><td>결제완료</td><td>PAYMENT</td></tr><tr><td>상품준비중</td><td>GOODS_READY</td></tr><tr><td>구매발주</td><td>GOODS_PLACEMENT</td></tr><tr><td>상품입고</td><td>GOODS_RECEIVED</td></tr><tr><td>상품출고</td><td>GOODS_SHIPPED</td></tr><tr><td>배송중</td><td>DELIVERY</td></tr><tr><td>배송완료</td><td>DELIVERY_COMPLETE</td></tr><tr><td>구매확정</td><td>SETTLE</td></tr><tr><td>자동취소</td><td>CANCEL_AUTO</td></tr><tr><td>품절취소</td><td>CANCEL_OUT_OF_STOCK</td></tr><tr><td>관리자취소</td><td>CANCEL_ADMIN</td></tr><tr><td>고객취소요청</td><td>CANCEL_CUSTOMER_REQUEST</td></tr><tr><td>반품접수</td><td>BACK_REQUEST</td></tr><tr><td>반송중 (반품)</td><td>BACK_IN_TRANSIT</td></tr><tr><td>반품보류</td><td>BACK_ON_HOLD</td></tr><tr><td>반품회수완료</td><td>BACK_COMPLETE</td></tr><tr><td>교환접수</td><td>EXCHANGE_REQUEST</td></tr><tr><td>반송중 (교환)</td><td>EXCHANGE_IN_TRANSIT</td></tr><tr><td>재배송중</td><td>EXCHANGE_REDELIVERY</td></tr><tr><td>교환보류</td><td>EXCHANGE_ON_HOLD</td></tr><tr><td>교환완료</td><td>EXCHANGE_COMPLETE</td></tr><tr><td>환불접수</td><td>REFUND_REQUEST</td></tr><tr><td>환불보류</td><td>REFUND_ON_HOLD</td></tr><tr><td>환불완료</td><td>REFUND_COMPLETE</td></tr></tbody></table>

***

#### <mark style="color:$info;">\[참고] 결제 수단 코드값</mark>

| 에스크로 계좌이체     | 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 |