# \[고도몰] 웹훅(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")

***

## 이해하기

* 웹훅이란 서버에서 특정 이벤트 발생했을 때 다른 서비스나 응용프로그램으로 알림을 보내는 기능입니다.
* 이를 사용하면 특정 이벤트가 발생한 시점에 지정한 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 | 주문 상품 상태 변경 |

***

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

### 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
    }
]
```

***

#### <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 |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://workspace-help.nhn-commerce.com/app-guide/godomall_webhook.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.