> ## Documentation Index
> Fetch the complete documentation index at: https://docs.steppay.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# 웹훅 V1 (deprecated)

<Warning>
  **Webhook V1 지원 종료 안내**

  V2 출시로 인하여 V1 웹훅은 공식적으로 지원이 종료되었습니다. V2로 업그레이드를 진행해주시고 업그레이드가 완료된 후에는 이전 버전 웹훅의 연동을 해지해주시기 바랍니다. '비관리형 결제'를 이용하시는 경우에는 기존 결제 웹훅을 해지하지 않으셔도 됩니다. **연동 해지**는 '스텝페이 포탈 > 설정 > 웹훅 설정'에 접속하시고 상단의 버전을 V1으로 변경해주시면 됩니다.
</Warning>

웹훅이란 특정 이벤트가 발생했을 때, 실시간으로 이벤트에 대한 정보를 가맹점 서버로 전달하는 기능을 말합니다. 예를 들어, 새로운 주문이 생성되거나, 구독 상태가 변경되었을 때 이를 즉시 가맹점에게 알려줍니다.

# 연관 가이드

* [주문 가이드](/docs/05_주문)
* [구독 가이드](/docs/06_구독)
* [결제 가이드](/docs/07-0_결제)

# 사전 준비 작업

웹훅을 사용하려면 스텝페이 포탈에서 \[설정 → 결제 설정 → 웹훅 설정]으로 이동해 웹훅을 등록해야 합니다.

![웹훅 설정](https://docs-image-translator-steppay.vercel.app/api/localize?dir=08_webhook\&name=setting_web_hook.png)

# 웹훅 이벤트 유형

스텝페이의 웹훅 이벤트는 다음과 같습니다. 이벤트 유형별로 연동 설정이 가능하며, 각 이벤트는 특정 상황에서 발생합니다.

| 이벤트 유형 | 설명                                                                                                                                                                                              |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 주문     | 갱신 주문이 성공했을 때 호출됩니다. 최초 주문은 호출되지 않습니다.                                                                                                                                                          |
| 구독     | 구독의 상태가 변경되었을 때 호출됩니다. 최초 생성시에도 호출됩니다.                                                                                                                                                          |
| 결제     | 비관리형 결제 사용 시 제공되는 웹훅입니다. ([결제 가이드 > 비관리형(Self) 결제 가이드 > 결제 웹훅](https://docs.steppay.kr/docs/%EB%B9%84%EA%B4%80%EB%A6%AC%ED%98%95self-%EA%B2%B0%EC%A0%9C#%EA%B2%B0%EC%A0%9C-%EC%9B%B9%ED%9B%85)) |

> 주의사항
>
> 웹훅은 인증 없이 동작하기 때문에 웹훅 엔드포인트 주소가 노출될 경우 악용될 가능성이 있습니다. 따라서 웹훅을 통해 전달받은 정보는 항상 백엔드에서 한 번 더 주문이나 결제 또는 구독에 대한 검증을 거친 후에 처리하시기 바랍니다.

# 연동 가이드

아래에서는 각 웹훅 이벤트에 대해 어떤 정보를 받을 수 있는지, 그리고 이 정보를 어떻게 사용해야 하는지에 대해 설명합니다.

## 주문 웹훅

갱신 주문이 성공했을 때 발생하며, 이를 통해 실시간으로 성공 알림을 받을 수 있습니다. 실패했을 때는 웹훅이 전송되지 않습니다. **단, 최초 주문시엔 발생하지 않습니다.**

<img src="https://docs-image-translator-steppay.vercel.app/api/localize?dir=08_webhook&name=order_web_hook_flow.png" width="30%" />

### 요청 형식

| HTTP Method  | POST             |
| ------------ | ---------------- |
| Content-Type | application/json |

### 웹훅 본문

| Feild       | Type   | Required | Description |
| ----------- | ------ | -------- | ----------- |
| webHookType | String | 필수       | 웹훅 타입       |
| orderId     | Long   | 필수       | 주문 번호       |

#### 웹훅 타입

지원하는 웹훅 타입은 아래와 같지만 '주문 웹훅'의 경우 'PAYMENT'만 전달됩니다.

| 상태                   | 설명                                     |
| -------------------- | -------------------------------------- |
| PAYMENT              | 결제 완료                                  |
| VBANK                | 가상계좌 발급 완료                             |
| CANCELED             | 결제 취소 완료                               |
| USER\_CANCELED       | 결제창에서 취소버튼을 눌렀을 때                      |
| FAILED               | 결제 실패                                  |
| CMS                  | CMS로 최초 결제                             |
| BILLKEY (deprecated) | 결제 완료 (0원인 경우)<br />-`PAYMENT` 로 변경 예정 |

```json theme={null}
{
  "webHookType": "PAYMENT",
  "orderId": 1
}
```

> 주문 웹훅이 발송되지 않는 경우
>
> * 최초 주문일 때
> * 단건 주문일 때
> * 구독 주문 갱신 시, 결제 실패일 때
> * 구독 주문 갱신 시, 결제 금액이 0원일 때

## 구독 웹훅

구독 상태 변경 웹훅은 구독의 상태가 변경되었을 때 발생합니다. 구독의 상태가 활성화, 일시정지, 만료 등으로 변경되었을 때 실시간으로 이를 알 수 있습니다. 구독 최초 생성 시에도 웹훅이 발생합니다.

<img src="https://docs-image-translator-steppay.vercel.app/api/localize?dir=08_webhook&name=subscription_web_hook_flow.png" width="50%" />

### 요청 형식

| HTTP Method  | POST             |
| ------------ | ---------------- |
| Content-Type | application/json |

### 웹훅 본문

| Feild  | Type   | Required | Description |
| ------ | ------ | -------- | ----------- |
| id     | Long   | 필수       | 구독 번호       |
| status | String | 필수       | 구독 상태       |

#### 구독 상태

| 구독 상태           | 설명         |
| --------------- | ---------- |
| ACTIVE          | 활성화        |
| UNPAID          | 결제 실패      |
| PENDING\_PAUSE  | 일시정지 예정    |
| PAUSE           | 일시 정지      |
| PENDING\_CANCEL | 취소 예정      |
| EXPIRED         | 구독 만료      |
| CANCELED        | 사용자에 의한 취소 |

```json theme={null}
{
  "id": 1,
  "status": "ACTIVE"
}
```