# Webhook

***

<figure><img src="https://3639913499-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnmQcxJVYbkAeUq7yQCkF%2Fuploads%2Fgit-blob-dacc8cbaf7d90293becccb3abb5706e4cd65c3fc%2Ffilename%20-%202025-10-14T171658.266.png?alt=media" alt="웹훅 추가 경로 화면"><figcaption></figcaption></figure>

***

## Webhook 등록 <a href="#registration" id="registration"></a>

`설정` <mark style="color:$primary;">></mark> `연동 설정` 메뉴에서 웹훅을 등록할 수 있습니다.

## Webhook 핸들러 <a href="#delivery-and-retry-behavior" id="delivery-and-retry-behavior"></a>

이벤트 발생 시 등록된 Webhook Endpoint로 이벤트 본문을 전달합니다. webhook 핸들러 응답 status code가 200인 경우 정상적으로 수신된 것으로 판단합니다. 만약 200이 아닌 status code가 반환되는 경우, 일시적 오류로 간주하여 최대 3번까지 재시도합니다.

## 이벤트 본문 <a href="#delivery-and-retry-behavior" id="delivery-and-retry-behavior"></a>

이벤트 전달 시, `POST` Body에 아래 데이터를 `JSON` 형태로 포함하여 전달합니다.

```json
{
  "id": "1234", // 이벤트의 고유 ID
  "topic": "txs/new", // 이벤트 주제
  "version": 1, // 이벤트 본문의 버전
  "payload": { // 이벤트 본문
    ...
  },
  "created_time": "2024-08-06T09:20:48.623Z" // 이벤트 발생 시간
}
```

## 이벤트 순서 <a href="#event-ordering" id="event-ordering"></a>

박스히어로는 이벤트의 전달 순서를 보장하지 않습니다.

예를 들어, `item/new` 이벤트가 `item/delete` 이벤트 이후에 도착할 수 있습니다. 응답 본문의 `created_time` 필드는 이벤트 실제 발생 시각을 의미하므로, 이를 활용해 적절히 처리될 수 있도록 직접 구현해 주세요.

## 이벤트 주제 <a href="#event-topics" id="event-topics"></a>

필요한 주제가 있다면 [**고객센터**](https://www.boxhero.io/docs/documentation/ko/contact)로 문의해주세요.

### txs/new

새롭게 재고 변동 내역(입고,출고,조정,이동)이 작성되었을 때 발송됩니다.

<table><thead><tr><th width="242">필드명</th><th width="97" data-type="checkbox">필수 여부</th><th>설명</th><th data-hidden data-type="checkbox">필수여부</th><th data-hidden>설명</th><th data-hidden>팀모드</th></tr></thead><tbody><tr><td>id</td><td>true</td><td>재고 변동 내역의 고유 ID</td><td>true</td><td>히스토리의 고유한 ID</td><td>전체</td></tr><tr><td>type</td><td>true</td><td>재고 변동 유형<br>(입고->in, 출고->out, 조정->adjust, 이동->move)</td><td>true</td><td><p>히스토리의 유형.</p><ul><li>입고 : in</li><li>출고 : out</li><li>조정 : adjust</li><li>이동 : move</li></ul></td><td>전체</td></tr><tr><td>partner</td><td>false</td><td>거래처</td><td>false</td><td></td><td></td></tr><tr><td>partner.id</td><td>false</td><td>거래처의 고유 ID</td><td>false</td><td></td><td></td></tr><tr><td>partner.name</td><td>false</td><td>거래처의 이름</td><td>false</td><td></td><td></td></tr><tr><td>partner.deleted</td><td>false</td><td>삭제된 거래처 여부</td><td>false</td><td></td><td></td></tr><tr><td>from_location</td><td>false</td><td>출발 위치</td><td>false</td><td></td><td></td></tr><tr><td>from_location.id</td><td>false</td><td>위치의 고유 ID</td><td>false</td><td></td><td></td></tr><tr><td>from_location.name</td><td>false</td><td>위치명</td><td>false</td><td></td><td></td></tr><tr><td>from_location.deleted</td><td>false</td><td>삭제된 위치 여부</td><td>false</td><td></td><td></td></tr><tr><td>to_location</td><td>true</td><td>도착 위치</td><td>false</td><td></td><td></td></tr><tr><td>to_location.id</td><td>true</td><td>위치의 고유 ID</td><td>false</td><td></td><td></td></tr><tr><td>to_location.name</td><td>true</td><td>위치명</td><td>false</td><td></td><td></td></tr><tr><td>to_location.deleted</td><td>true</td><td>삭제된 위치 여부</td><td>false</td><td></td><td></td></tr><tr><td>items</td><td>true</td><td>히스토리 품목</td><td>true</td><td>히스토리를 구성하는 제품별 항목</td><td>모든 모드</td></tr><tr><td>items.id</td><td>true</td><td>제품의 고유 ID</td><td>true</td><td>제품의 고유 ID</td><td>모든 모드</td></tr><tr><td>items.name</td><td>true</td><td>제품명</td><td>true</td><td>제품의 이름</td><td>모든 모드</td></tr><tr><td>items.quantity</td><td>true</td><td>입고/출고/조정/이동에 의한 재고의 변경량</td><td>true</td><td>해당 제품의 입고/출고/조정/이동 수량</td><td>모든 모드</td></tr><tr><td>items.deleted</td><td>true</td><td>제품의 삭제 여부</td><td>true</td><td>삭제된 제품 여부</td><td></td></tr><tr><td>items.from_location_new_stock_level</td><td>false</td><td>재고 변동 이후, 출발 위치에서의 재고 수량</td><td>false</td><td></td><td></td></tr><tr><td>items.to_location_new_stock_level</td><td>true</td><td>재고 변동 이후, 도착 위치에서의 재고 수량</td><td>false</td><td></td><td></td></tr><tr><td>transaction_time</td><td>true</td><td>트랜잭션 시점(e.g. 입/출고 시간)</td><td>false</td><td></td><td></td></tr><tr><td>created_at</td><td>true</td><td>재고 변동 내역이 작성된 시점</td><td>false</td><td></td><td></td></tr><tr><td>created_by</td><td>true</td><td>재고 변동 내역을 작성한 멤버</td><td>false</td><td></td><td></td></tr><tr><td>created_by.id</td><td>true</td><td>멤버의 고유 ID</td><td>false</td><td></td><td></td></tr><tr><td>created_by.name</td><td>true</td><td>멤버의 이름</td><td>false</td><td></td><td></td></tr><tr><td>created_by.deleted</td><td>true</td><td>탈퇴한 멤버 여부</td><td>false</td><td></td><td></td></tr><tr><td>count_of_items</td><td>true</td><td>제품별 항목수</td><td>false</td><td></td><td></td></tr><tr><td>total_quantity</td><td>true</td><td>재고 변동량의 총합</td><td>false</td><td></td><td></td></tr><tr><td>url</td><td>true</td><td>재고 변동 상세 내역 페이지로 이동할 수 있는 주소</td><td>false</td><td></td><td></td></tr><tr><td>memo</td><td>false</td><td>메모</td><td>false</td><td></td><td></td></tr></tbody></table>

{% hint style="danger" %}
엑셀로 제품을 대량 추가하거나 수정할 때 생성된 조정 내역은 발송되지 않습니다.
{% endhint %}

#### 이벤트 본문 예시 : 입고 이벤트가 발생

```json
{
  "id": 16160911,
  "type": "in",
  "to_location": {
    "id": 52766,
    "name": "Warehouse 3",
    "deleted": false
  },
  "items": [
    {
      "id": 14277699,
      "name": "belif Cleansing Gel Oil Enriched",
      "quantity": 2,
      "deleted": false,
      "to_location_new_stock_level": 3
    },
    {
      "id": 14277698,
      "name": "belif Aqua Bomb Jelly Cleanser",
      "quantity": 2,
      "deleted": false,
      "to_location_new_stock_level": 5
    }
  ],
  "transaction_time": "2023-04-25T05:42:27.545Z",
  "created_at": "2023-08-14T05:14:29.499Z",
  "created_by": {
    "id": 201345,
    "name": "corp",
    "deleted": false
  },
  "count_of_items": 2,
  "total_quantity": 4,
  "url": "https://web.boxhero-app.com/team/149058/mode/0#/tx/16160911"
}
```

#### 이벤트 본문 예시 : 이동 이벤트가 발생

```json
{
  "id": 3692714,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "Warehouse 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Warehouse 3",
    "deleted": false
  },
  "items": [
    {
      "id": 14873303,
      "name": "Auto liner 3.5mm",
      "quantity": 1,
      "deleted": false,
      "from_location_new_stock_level": -1,
      "to_location_new_stock_level": 1
    }
  ],
  "transaction_time": "2023-04-25T05:42:27.545Z",
  "created_at": "2023-04-25T05:42:27.545Z",
  "created_by": {
    "id": 176829,
    "name": "Joy Kim",
    "deleted": false
  },
  "count_of_items": 1,
  "total_quantity": 1,
  "url": "https://web.boxhero-app.com/team/150581/mode/2#/ltx/3692714"
}
```

### txs/edit

기존 재고 변동 내역(입고,출고,조정,이동)이 수정되었을 때 발송됩니다.

<table><thead><tr><th width="242">필드명</th><th width="97" data-type="checkbox">필수 여부</th><th>설명</th><th data-hidden data-type="checkbox">필수여부</th><th data-hidden>설명</th><th data-hidden>팀모드</th></tr></thead><tbody><tr><td>id</td><td>true</td><td>재고 변동 내역의 고유 ID</td><td>true</td><td>히스토리의 고유한 ID</td><td>전체</td></tr><tr><td>type</td><td>true</td><td>재고 변동 유형<br>(입고->in, 출고->out, 조정->adjust, 이동->move)</td><td>true</td><td><p>히스토리의 유형.</p><ul><li>입고 : in</li><li>출고 : out</li><li>조정 : adjust</li><li>이동 : move</li></ul></td><td>전체</td></tr><tr><td>partner</td><td>false</td><td>거래처</td><td>false</td><td></td><td></td></tr><tr><td>partner.id</td><td>false</td><td>거래처의 고유 ID</td><td>false</td><td></td><td></td></tr><tr><td>partner.name</td><td>false</td><td>거래처의 이름</td><td>false</td><td></td><td></td></tr><tr><td>partner.deleted</td><td>false</td><td>삭제된 거래처 여부</td><td>false</td><td></td><td></td></tr><tr><td>from_location</td><td>false</td><td>출발 위치</td><td>false</td><td></td><td></td></tr><tr><td>from_location.id</td><td>false</td><td>위치의 고유 ID</td><td>false</td><td></td><td></td></tr><tr><td>from_location.name</td><td>false</td><td>위치명</td><td>false</td><td></td><td></td></tr><tr><td>from_location.deleted</td><td>false</td><td>삭제된 위치 여부</td><td>false</td><td></td><td></td></tr><tr><td>to_location</td><td>true</td><td>도착 위치</td><td>false</td><td></td><td></td></tr><tr><td>to_location.id</td><td>true</td><td>위치의 고유 ID</td><td>false</td><td></td><td></td></tr><tr><td>to_location.name</td><td>true</td><td>위치명</td><td>false</td><td></td><td></td></tr><tr><td>to_location.deleted</td><td>true</td><td>삭제된 위치 여부</td><td>false</td><td></td><td></td></tr><tr><td>items</td><td>true</td><td>히스토리 품목</td><td>true</td><td>히스토리를 구성하는 제품별 항목</td><td>모든 모드</td></tr><tr><td>items.id</td><td>true</td><td>제품의 고유 ID</td><td>true</td><td>제품의 고유 ID</td><td>모든 모드</td></tr><tr><td>items.name</td><td>true</td><td>제품명</td><td>true</td><td>제품의 이름</td><td>모든 모드</td></tr><tr><td>items.quantity</td><td>true</td><td>입고/출고/조정/이동에 의한 재고의 변경량</td><td>true</td><td>해당 제품의 입고/출고/조정/이동 수량</td><td>모든 모드</td></tr><tr><td>items.deleted</td><td>true</td><td>제품의 삭제 여부</td><td>true</td><td>삭제된 제품 여부</td><td></td></tr><tr><td>items.from_location_new_stock_level</td><td>false</td><td>재고 변동 이후, 출발 위치에서의 재고 수량</td><td>false</td><td></td><td></td></tr><tr><td>items.to_location_new_stock_level</td><td>true</td><td>재고 변동 이후, 도착 위치에서의 재고 수량</td><td>false</td><td></td><td></td></tr><tr><td>transaction_time</td><td>true</td><td>트랜잭션 시점(e.g. 입/출고 시간)</td><td>false</td><td></td><td></td></tr><tr><td>created_at</td><td>true</td><td>재고 변동 내역이 작성된 시점</td><td>false</td><td></td><td></td></tr><tr><td>created_by</td><td>true</td><td>재고 변동 내역을 작성한 멤버</td><td>false</td><td></td><td></td></tr><tr><td>created_by.id</td><td>true</td><td>멤버의 고유 ID</td><td>false</td><td></td><td></td></tr><tr><td>created_by.name</td><td>true</td><td>멤버의 이름</td><td>false</td><td></td><td></td></tr><tr><td>created_by.deleted</td><td>true</td><td>탈퇴한 멤버 여부</td><td>false</td><td></td><td></td></tr><tr><td>count_of_items</td><td>true</td><td>제품별 항목수</td><td>false</td><td></td><td></td></tr><tr><td>total_quantity</td><td>true</td><td>재고 변동량의 총합</td><td>false</td><td></td><td></td></tr><tr><td>url</td><td>true</td><td>재고 변동 상세 내역 페이지로 이동할 수 있는 주소</td><td>false</td><td></td><td></td></tr><tr><td>memo</td><td>false</td><td>메모</td><td>false</td><td></td><td></td></tr><tr><td>reivison</td><td>true</td><td>재고 변동 내역의 현재 버전. 1부터 시작합니다.</td><td>false</td><td></td><td></td></tr></tbody></table>

#### 이벤트 본문 예시 : 입고 내역이 수정

```json
{
  "id": 16160911,
  "type": "in",
  "to_location": {
    "id": 52766,
    "name": "Warehouse 3",
    "deleted": false
  },
  "items": [
    {
      "id": 14277699,
      "name": "belif Cleansing Gel Oil Enriched",
      "quantity": 2,
      "deleted": false,
      "to_location_new_stock_level": 3
    },
    {
      "id": 14277698,
      "name": "belif Aqua Bomb Jelly Cleanser",
      "quantity": 2,
      "deleted": false,
      "to_location_new_stock_level": 5
    }
  ],
  "transaction_time": "2023-04-25T05:42:27.545Z",
  "created_at": "2023-08-14T05:14:29.499Z",
  "created_by": {
    "id": 201345,
    "name": "corp",
    "deleted": false
  },
  "count_of_items": 2,
  "total_quantity": 4,
  "url": "https://web.boxhero-app.com/team/149058/mode/0#/tx/16160911"
}
```

#### 이벤트 본문 예시 : 이동 내역이 수정

```json
{
  "id": 3692714,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "Warehouse 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Warehouse 3",
    "deleted": false
  },
  "items": [
    {
      "id": 14873303,
      "name": "Auto liner 3.5mm",
      "quantity": 1,
      "deleted": false,
      "from_location_new_stock_level": -1,
      "to_location_new_stock_level": 1
    }
  ],
  "transaction_time": "2023-04-25T05:42:27.545Z",
  "created_at": "2023-04-25T05:42:27.545Z",
  "created_by": {
    "id": 176829,
    "name": "Joy Kim",
    "deleted": false
  },
  "count_of_items": 1,
  "total_quantity": 1,
  "url": "https://web.boxhero-app.com/team/150581/mode/2#/ltx/3692714"
}
```

### txs/delete

재고 변동 내역이 삭제되었을 때 발송됩니다.

<table><thead><tr><th width="318">필드명</th><th>설명</th><th data-hidden data-type="checkbox">필수여부</th><th data-hidden>설명</th><th data-hidden>팀모드</th></tr></thead><tbody><tr><td>id</td><td>재고 변동 내역의 고유 ID</td><td>true</td><td>히스토리의 고유한 ID</td><td>전체</td></tr><tr><td>revision</td><td>재고 변동 내역의 현재 버전. 1부터 시작합니다.</td><td>true</td><td><p>히스토리의 유형.</p><ul><li>입고 : in</li><li>출고 : out</li><li>조정 : adjust</li><li>이동 : move</li></ul></td><td>전체</td></tr></tbody></table>

#### 이벤트 본문 예시

<pre class="language-json"><code class="lang-json">{
<strong>  "id": 27036740,
</strong>  "revision": 2
}
</code></pre>

### item/new

제품이 추가되었을 때 발송됩니다.

<table><thead><tr><th width="318">필드명</th><th>설명</th><th data-hidden data-type="checkbox">필수여부</th><th data-hidden>설명</th><th data-hidden>팀모드</th></tr></thead><tbody><tr><td>id</td><td>제품의 고유 ID</td><td>true</td><td>히스토리의 고유한 ID</td><td>전체</td></tr><tr><td>name</td><td>제품명</td><td>true</td><td><p>히스토리의 유형.</p><ul><li>입고 : in</li><li>출고 : out</li><li>조정 : adjust</li><li>이동 : move</li></ul></td><td>전체</td></tr><tr><td>sku</td><td>거래처</td><td>false</td><td></td><td></td></tr><tr><td>barcode</td><td>거래처의 고유 ID</td><td>false</td><td></td><td></td></tr><tr><td>photo_url</td><td>거래처의 이름</td><td>false</td><td></td><td></td></tr><tr><td>cost</td><td>삭제된 거래처 여부</td><td>false</td><td></td><td></td></tr><tr><td>price</td><td>출발 위치</td><td>false</td><td></td><td></td></tr><tr><td>attrs</td><td>제품 속성 데이터</td><td>false</td><td></td><td></td></tr></tbody></table>

{% hint style="danger" %}
옵션 일괄 추가 또는 엑셀 대량 추가 기능 사용 시에는 발송되지 않습니다.
{% endhint %}

#### 이벤트 본문 예시

```json
{
  "id": 26122826,
  "name": "belif Peat Miracle Revital Cream",
  "sku": "SKU-YH2361KI",
  "barcode": "2002074321218",
  "photo_url": "https://d3l9wd8kivvlqy.cloudfront.net/ap-northeast-2/image-up-ap-northeast-2/30b0cc84-601d-493d-87fd-b7e8b5825601",
  "cost": "50000",
  "price": "65000",
  "attrs": [
    {
      "id": 413101,
      "name": "Category",
      "type": "text",
      "value": "Foundation"
    },
    {
      "id": 459264,
      "name": "Expiration date",
      "type": "date",
      "value": "2024-08-07"
    },
    {
      "id": 668272,
      "name": "Safety Stock",
      "type": "number",
      "value": 33
    }
  ]
}
```

### item/edit

제품이 수정되었을 때 발송됩니다.

<table><thead><tr><th width="318">필드명</th><th>설명</th><th data-hidden data-type="checkbox">필수여부</th><th data-hidden>설명</th><th data-hidden>팀모드</th></tr></thead><tbody><tr><td>id</td><td>제품의 고유 ID</td><td>true</td><td>히스토리의 고유한 ID</td><td>전체</td></tr><tr><td>name</td><td>제품명</td><td>true</td><td><p>히스토리의 유형.</p><ul><li>입고 : in</li><li>출고 : out</li><li>조정 : adjust</li><li>이동 : move</li></ul></td><td>전체</td></tr><tr><td>sku</td><td>거래처</td><td>false</td><td></td><td></td></tr><tr><td>barcode</td><td>거래처의 고유 ID</td><td>false</td><td></td><td></td></tr><tr><td>photo_url</td><td>거래처의 이름</td><td>false</td><td></td><td></td></tr><tr><td>cost</td><td>삭제된 거래처 여부</td><td>false</td><td></td><td></td></tr><tr><td>price</td><td>출발 위치</td><td>false</td><td></td><td></td></tr><tr><td>attrs</td><td>제품 속성 데이터</td><td>false</td><td></td><td></td></tr></tbody></table>

{% hint style="danger" %}
`데이터 관리` > `제품` 에서 엑셀대량 수정 기능 사용 시에는 발송되지 않습니다.
{% endhint %}

#### 이벤트 본문 예시

```json
{
  "id": 26122826,
  "name": "belif Peat Miracle Revital Cream",
  "sku": "SKU-YH2361KI",
  "barcode": "2002074321218",
  "photo_url": "https://d3l9wd8kivvlqy.cloudfront.net/ap-northeast-2/image-up-ap-northeast-2/30b0cc84-601d-493d-87fd-b7e8b5825601",
  "cost": "50000",
  "price": "65000",
  "attrs": [
    {
      "id": 413101,
      "name": "Category",
      "type": "text",
      "value": "Foundation"
    },
    {
      "id": 459264,
      "name": "Expiration date",
      "type": "date",
      "value": "2024-08-07"
    },
    {
      "id": 668272,
      "name": "Safety Stock",
      "type": "number",
      "value": 33
    }
  ]
}
```

### item/delete

제품이 삭제되었을 때 발송됩니다.

<table><thead><tr><th width="318">필드명</th><th>설명</th><th data-hidden data-type="checkbox">필수여부</th><th data-hidden>설명</th><th data-hidden>팀모드</th></tr></thead><tbody><tr><td>id</td><td>제품의 고유 ID</td><td>true</td><td>히스토리의 고유한 ID</td><td>전체</td></tr></tbody></table>

{% hint style="danger" %}
`데이터 관리` > `제품` 에서 엑셀대량 삭제 기능 사용 시에는 발송되지 않습니다.
{% endhint %}

#### 이벤트 본문 예시

```json
{
  "id": 26122826
}
```