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


---

# 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://www.boxhero.io/docs/documentation/ko/etc/settings/integrations/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.