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

# 웹훅 V2

> 스텝페이에서 발생하는 다양한 이벤트를 실시간으로 알려주는 웹훅 V2의 사용 방법과 연동 가이드

<img src="https://docs-image-translator-steppay.vercel.app/api/localize?dir=08_webhook&name=webhook_2.png" width="90%" style={{ display: "block", margin: "0 auto", transition: "none" }} />

웹훅이란 스텝페이에서 발생하는 정보를 실시간으로 알려주는 기능입니다. 다양한 [스텝페이 이벤트](/docs/08-1-1_Webhook-Events)를 제공하고 있으며 원하는 이벤트만 연동하여 수신받으실 수 있습니다.

# **웹훅 사용 하기**

아래의 순서대로 웹훅 연동을 위한 준비하실 수 있습니다. 그리고 이벤트 유형에 맞는 액션이 발생하면 웹훅이 전송됩니다. 상세 페이지에서 전송 내역을 확인하실 수 있습니다.

#### `STEP 1`

* 웹훅을 수신 받을 end-point를 준비합니다. 수신받으실 데이터는 [API Spec](#api-spec)를 참조해주세요.

#### `STEP 2`

* 연동할 API end-point URL을 [스텝페이 포탈](https://portal.steppay.kr/setting/webhook)에서 등록하실 수 있습니다.

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

#### `STEP 3`

* 등록한 이벤트를 받아볼 수 있는 액션을 합니다. (예. ‘청구서 생성’ 이벤트를 연동했을 경우, 청구서를 생성한다.)

#### `STEP 4`

* 웹훅 상세보기 페이지에서 전송 내역을 확인합니다.

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

## 주의사항

> 웹훅 이벤트를 전송하는 순서는 보장되지 않습니다.
>
> 웹훅 이벤트는 실시간으로 발생하며, 이를 통해 사용자에게 빠른 업데이트를 제공하려고 노력합니다. 그러나 네트워크 지연, 서버 처리 시간 등의 이유로 인해, 이벤트의 전송 순서가 원래의 발생 순서와 일치하지 않을 수 있습니다. 이는 웹훅 구조의 특성상 피할 수 없는 문제로, 이벤트를 수신하는 시스템이 이벤트의 순서를 가정하고 동작하도록 설계되어 있다면 문제가 발생할 수 있습니다.
>
> 이러한 이유로, 웹훅 이벤트를 처리하는 로직은 반드시 이벤트가 순서대로 전달되지 않을 수 있다는 것을 고려하여 설계되어야 합니다. 이벤트 순서에 의존하는 처리를 최소화하고, 가능한 각 이벤트를 독립적으로 처리할 수 있도록 하는 것이 좋습니다. 이 점을 유념하시어 웹훅을 사용하실 때 발생할 수 있는 문제에 대비하시기 바랍니다.

# 웹훅 연동하기

웹훅 연동에 필요한 정보입니다. 전달하는 Spec은 기본적으로 동일하며, Spec 내의 `data` 프로퍼티가 이벤트별로 가변적입니다. 스텝페이가 제공하는 이벤트를 확인하시고 이벤트에 맞는 스키마를 대응해서 데이터를 수신받으실 수 있습니다.

* [Webhook Events](/docs/08-1-1_Webhook-Events)

* [Webhook Schema](/docs/08-1-2_Webhook-Schema)

## **API Spec**

웹훅으로 부터 받을 수 있는 API Spec입니다. 현재 지원하는 **Content-Type**은 '**application/json**'만 가능합니다.

### ✔️ **Webhook Request**

아래는 webhook request 정보를 설명하는 표입니다. 모든 웹훅 요청은 아래의 규격으로 전송되며, `event(이벤트 타입)` 으로 이벤트를 구분할 수 있습니다.

| 변수명       | 타입     | description |
| --------- | ------ | ----------- |
| timestamp | Long   | timestamp   |
| version   | String | API Version |
| event     | String | 이벤트 타입      |
| data      | Object | Schema      |

* **JSON Example**

```json theme={null}
{
  "timestamp": 1688697915,
  "version": "v1",
  "event": "subscription.usage.added",
  "data": {...} // version과 매칭되는 Schema
}
```

## 웹훅 테스트

### 수신 데이터 확인하기

연동 전에 수신되는 데이터만 확인해보고 싶은 경우에 다음의 방법으로 데이터를 확인해볼 수 있습니다.

#### `STEP 1`

* [https://webhook.site](https://webhook.site) 를 접속합니다.

#### `STEP 2`

* 페이지의 **Your unique URL** 를 복사합니다.

  ![웹훅 사이트1](https://docs-image-translator-steppay.vercel.app/api/localize?dir=08_webhook\&name=webhook_site_1.jpeg)

#### `STEP 3`

* 포탈에 해당 URL로 이벤트를 등록합니다.

  ![웹훅 사이트1](https://docs-image-translator-steppay.vercel.app/api/localize?dir=08_webhook\&name=webhook_url.png)

#### `STEP 4`

* 이벤트에 해당하는 액션을 취합니다. 예시의 경우 '결제완료(payment.completed)' 액션을 수행합니다.

#### `STEP 5`

* [https://webhook.site](https://webhook.site/) 에서 수신받은 데이터를 확인합니다. 예시는 ‘결제완료(payment.completed)’이벤트를 수신받은 결과 입니다.

  ![웹훅 사이트2](https://docs-image-translator-steppay.vercel.app/api/localize?dir=08_webhook\&name=webhook_site_2.jpeg)