# Webhook

<figure><img src="https://687823928-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlRf1QqJGoevCQqGbfI80%2Fuploads%2Fgit-blob-094f1326e4f5b66d3f4de825a63e55cbf0f4ac01%2Fboxhero-add-webhook.png?alt=media" alt=""><figcaption></figcaption></figure>

***

## Registration

You can register a webhook at <mark style="color:blue;">**`Settings`**</mark> **>** <mark style="color:blue;">**`Integrations & API`**</mark> in your BoxHero team.

## Delivery & Retry Behavior

When an event occurs, BoxHero sends an HTTP `POST` request to your registered webhook endpoint. The request body contains a JSON payload describing the event.

* If your server responds with **HTTP 200 OK**, the event is considered successfully delivered.
* If your server responds with **any non-200 status code**, BoxHero treats it as a temporary failure and retries delivery up to 3 times.

## Webhook Payload Structure

All webhook events are delivered with the following JSON structure in the request body:

```json
{
  "id": "1234", // Event's unique ID
  "topic": "txs/new", // Event topic
  "version": 1, // Payload schema version
  "payload": { // Event-specific data
    ...
  },
  "created_time": "2025-08-06T09:20:48.623Z" // Timestamp of event occurrence (ISO 8601)
}
```

***

## Event Ordering

BoxHero **does not** guarantee the order of event delivery. For example, an `item/new` event may arrive after an `item/delete` event for the same item.

The `created_time` field in the event payload represents the actual event time. Implement idempotent and order-tolerant logic in your webhook handler to handle events reliably.

## Event Topics

{% hint style="info" %}
If you need support for additional event topics, please contact [Support](https://www.boxhero.io/docs/resources/contact).
{% endhint %}

### `txs/new`

Triggered when an inventory transaction occurs (Stock In / Stock Out / Adjust Stock / Move Stock).

{% hint style="warning" %}
**Note:** This event is *not* triggered for adjustments created through bulk edits or imports (e.g., when adding or updating items via Excel).
{% endhint %}

<table><thead><tr><th width="207">Field</th><th width="100" data-type="checkbox">Required</th><th>Description</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>Transaction's unique ID</td><td>true</td><td>히스토리의 고유한 ID</td><td>전체</td></tr><tr><td>type</td><td>true</td><td>Transaction type<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>Partner</td><td>false</td><td></td><td></td></tr><tr><td>partner.id</td><td>false</td><td>Partner's unique ID</td><td>false</td><td></td><td></td></tr><tr><td>partner.name</td><td>false</td><td>Partner's name</td><td>false</td><td></td><td></td></tr><tr><td>partner.deleted</td><td>false</td><td>Whether the partner is deleted</td><td>false</td><td></td><td></td></tr><tr><td>from_location</td><td>false</td><td>Source location</td><td>false</td><td></td><td></td></tr><tr><td>from_location.id</td><td>false</td><td>Source location's unique ID</td><td>false</td><td></td><td></td></tr><tr><td>from_location.name</td><td>false</td><td>Source location name</td><td>false</td><td></td><td></td></tr><tr><td>from_location.deleted</td><td>false</td><td>Whether the source location is deleted</td><td>false</td><td></td><td></td></tr><tr><td>to_location</td><td>true</td><td>Destination location</td><td>false</td><td></td><td></td></tr><tr><td>to_location.id</td><td>true</td><td>Destination location's unique ID</td><td>false</td><td></td><td></td></tr><tr><td>to_location.name</td><td>true</td><td>Destination location name</td><td>false</td><td></td><td></td></tr><tr><td>to_location.deleted</td><td>true</td><td>Whether the destination location is deleted</td><td>false</td><td></td><td></td></tr><tr><td>items</td><td>true</td><td>Line items in transaction</td><td>true</td><td>히스토리를 구성하는 제품별 항목</td><td>모든 모드</td></tr><tr><td>items.id</td><td>true</td><td>Item's unique ID</td><td>true</td><td>제품의 고유 ID</td><td>모든 모드</td></tr><tr><td>items.name</td><td>true</td><td>Item name</td><td>true</td><td>제품의 이름</td><td>모든 모드</td></tr><tr><td>items.quantity</td><td>true</td><td>Inventory change due to stock in/out/adjust/move</td><td>true</td><td>해당 제품의 입고/출고/조정/이동 수량</td><td>모든 모드</td></tr><tr><td>items.deleted</td><td>true</td><td>Whether the item is deleted</td><td>true</td><td>삭제된 제품 여부</td><td></td></tr><tr><td>items.from_location_new_stock_level</td><td>false</td><td>The stock level at source location after the transaction</td><td>false</td><td></td><td></td></tr><tr><td>items.to_location_new_stock_level</td><td>true</td><td>The stock level at destination location after the transaction</td><td>false</td><td></td><td></td></tr><tr><td>transaction_time</td><td>true</td><td>Transaction time (e.g. stock in/out time)</td><td>false</td><td></td><td></td></tr><tr><td>created_at</td><td>true</td><td>The time when the transaction was created</td><td>false</td><td></td><td></td></tr><tr><td>created_by</td><td>true</td><td>Member who created the transaction</td><td>false</td><td></td><td></td></tr><tr><td>created_by.id</td><td>true</td><td>Member's unique ID</td><td>false</td><td></td><td></td></tr><tr><td>created_by.name</td><td>true</td><td>Member name</td><td>false</td><td></td><td></td></tr><tr><td>created_by.deleted</td><td>true</td><td>Whether the member is deleted</td><td>false</td><td></td><td></td></tr><tr><td>count_of_items</td><td>true</td><td>The number of items</td><td>false</td><td></td><td></td></tr><tr><td>total_quantity</td><td>true</td><td>The total amount of inventory change</td><td>false</td><td></td><td></td></tr><tr><td>url</td><td>true</td><td>URL address to view the transaction details page</td><td>false</td><td></td><td></td></tr><tr><td>memo</td><td>false</td><td>Notes related to the transaction</td><td>false</td><td></td><td></td></tr></tbody></table>

#### Example Webhook Payload – `Stock In` Event

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

#### Example Webhook Payload – `Move Stock` Event

<pre class="language-json"><code class="lang-json">{
  "id": 3692714,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "Warehouse 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Warehouse 3",
<strong>    "deleted": false
</strong>  },
  "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": "2025-04-25T05:42:27.545Z",
  "created_at": "2025-04-25T05:42:27.545Z",
  "created_by": {
    "id": 176829,
    "name": "Tony Lee",
    "deleted": false
  },
  "count_of_items": 1,
  "total_quantity": 1,
  "url": "https://web.boxhero-app.com/team/150581/mode/2#/ltx/3692714"
}
</code></pre>

### `txs/edit`

Sent when an existing inventory transaction (Stock In / Stock Out / Adjust Stock / Move Stock) is **edited**.

<table><thead><tr><th>Field</th><th width="100" data-type="checkbox">Required</th><th>Description</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>Transaction's unique ID</td><td>true</td><td>히스토리의 고유한 ID</td><td>전체</td></tr><tr><td>type</td><td>true</td><td>Transaction type<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>Partner</td><td>false</td><td></td><td></td></tr><tr><td>partner.id</td><td>false</td><td>Partner's unique ID</td><td>false</td><td></td><td></td></tr><tr><td>partner.name</td><td>false</td><td>Partner's name</td><td>false</td><td></td><td></td></tr><tr><td>partner.deleted</td><td>false</td><td>Whether the partner is deleted</td><td>false</td><td></td><td></td></tr><tr><td>from_location</td><td>false</td><td>Source location</td><td>false</td><td></td><td></td></tr><tr><td>from_location.id</td><td>false</td><td>Source location's unique ID</td><td>false</td><td></td><td></td></tr><tr><td>from_location.name</td><td>false</td><td>Source location name</td><td>false</td><td></td><td></td></tr><tr><td>from_location.deleted</td><td>false</td><td>Whether the source location is deleted</td><td>false</td><td></td><td></td></tr><tr><td>to_location</td><td>true</td><td>Destination location</td><td>false</td><td></td><td></td></tr><tr><td>to_location.id</td><td>true</td><td>Destination location's unique ID</td><td>false</td><td></td><td></td></tr><tr><td>to_location.name</td><td>true</td><td>Destination location name</td><td>false</td><td></td><td></td></tr><tr><td>to_location.deleted</td><td>true</td><td>Whether the destination location is deleted</td><td>false</td><td></td><td></td></tr><tr><td>items</td><td>true</td><td>Line items in transaction</td><td>true</td><td>히스토리를 구성하는 제품별 항목</td><td>모든 모드</td></tr><tr><td>items.id</td><td>true</td><td>Item's unique ID</td><td>true</td><td>제품의 고유 ID</td><td>모든 모드</td></tr><tr><td>items.name</td><td>true</td><td>Item name</td><td>true</td><td>제품의 이름</td><td>모든 모드</td></tr><tr><td>items.quantity</td><td>true</td><td>Quantity change due to transaction (in/out/adjust/move)</td><td>true</td><td>해당 제품의 입고/출고/조정/이동 수량</td><td>모든 모드</td></tr><tr><td>items.deleted</td><td>true</td><td>Whether the item is deleted</td><td>true</td><td>삭제된 제품 여부</td><td></td></tr><tr><td>items.from_location_new_stock_level</td><td>false</td><td>The stock level at source location after the transaction</td><td>false</td><td></td><td></td></tr><tr><td>items.to_location_new_stock_level</td><td>true</td><td>The stock level at destination location after the transaction</td><td>false</td><td></td><td></td></tr><tr><td>transaction_time</td><td>true</td><td>Transaction time (e.g. stock in/out time)</td><td>false</td><td></td><td></td></tr><tr><td>created_at</td><td>true</td><td>The time when the transaction was created</td><td>false</td><td></td><td></td></tr><tr><td>created_by</td><td>true</td><td>Member who created the transaction</td><td>false</td><td></td><td></td></tr><tr><td>created_by.id</td><td>true</td><td>Member's unique ID</td><td>false</td><td></td><td></td></tr><tr><td>created_by.name</td><td>true</td><td>Member name</td><td>false</td><td></td><td></td></tr><tr><td>created_by.deleted</td><td>true</td><td>Whether the member is deleted</td><td>false</td><td></td><td></td></tr><tr><td>count_of_items</td><td>true</td><td>The number of items</td><td>false</td><td></td><td></td></tr><tr><td>total_quantity</td><td>true</td><td>The total amount of inventory change</td><td>false</td><td></td><td></td></tr><tr><td>url</td><td>true</td><td>URL address to view the transaction details page</td><td>false</td><td></td><td></td></tr><tr><td>memo</td><td>false</td><td>Notes related to the transaction</td><td>false</td><td></td><td></td></tr><tr><td>revision</td><td>true</td><td>Current version number of the transaction, starting from 1</td><td>false</td><td></td><td></td></tr></tbody></table>

#### Example Webhook Payload – Edited `Stock In` Transaction

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

```

#### Example Webhook Payload – Edited `Move Stock` Transaction

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

Sent when an inventory transaction is **deleted**.

| Field    | Description                                                |
| -------- | ---------------------------------------------------------- |
| id       | Transaction's unique ID                                    |
| revision | Current version number of the transaction, starting from 1 |

#### Example Webhook Payload – Deleted Transaction

```json
/{
  "id": 27036740,
  "revision": 2
}
```

### `item/new`

Sent when a new item is added to the team's inventory.

{% hint style="warning" %}
**Note**: This event is *not* triggered when using the <mark style="color:blue;">**`Add Item Variants`**</mark> feature or importing items via <mark style="color:blue;">**`Import Excel`**</mark>.
{% endhint %}

<table><thead><tr><th width="318">Field</th><th>Description</th><th data-hidden data-type="checkbox">필수여부</th><th data-hidden>설명</th><th data-hidden>팀모드</th></tr></thead><tbody><tr><td>id</td><td>Item ID</td><td>true</td><td>히스토리의 고유한 ID</td><td>전체</td></tr><tr><td>name</td><td>Item Name</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>SKU</td><td>false</td><td></td><td></td></tr><tr><td>barcode</td><td>Barcode</td><td>false</td><td></td><td></td></tr><tr><td>photo_url</td><td>Photo URL</td><td>false</td><td></td><td></td></tr><tr><td>cost</td><td>Cost</td><td>false</td><td></td><td></td></tr><tr><td>price</td><td>Price</td><td>false</td><td></td><td></td></tr><tr><td>attrs</td><td>Attributes</td><td>false</td><td></td><td></td></tr></tbody></table>

#### **Example Payload – Item Created**

```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": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "Safety Stock",
      "type": "number",
      "value": 33
    }
  ]
}
```

### `item/edit`

Sent when an existing item is edited.

{% hint style="warning" %}
**Note**: This event is *not* triggered *f*or bulk edits made through <mark style="color:blue;">**`Data Center`**</mark>**&#x20;>&#x20;**<mark style="color:blue;">**`Item`**</mark> or via the <mark style="color:blue;">**`Import Excel`**</mark> function.
{% endhint %}

<table><thead><tr><th width="318">Field</th><th>Description</th><th data-hidden data-type="checkbox">필수여부</th><th data-hidden>설명</th><th data-hidden>팀모드</th></tr></thead><tbody><tr><td>id</td><td>Item ID</td><td>true</td><td>히스토리의 고유한 ID</td><td>전체</td></tr><tr><td>name</td><td>Item Name</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>SKU</td><td>false</td><td></td><td></td></tr><tr><td>barcode</td><td>Barcode</td><td>false</td><td></td><td></td></tr><tr><td>photo_url</td><td>Photo URL</td><td>false</td><td></td><td></td></tr><tr><td>cost</td><td>Cost</td><td>false</td><td></td><td></td></tr><tr><td>price</td><td>Price</td><td>false</td><td></td><td></td></tr><tr><td>attrs</td><td>Attributes</td><td>false</td><td></td><td></td></tr></tbody></table>

#### **Example Payload – Item Updated**

```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": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "Safety Stock",
      "type": "number",
      "value": 33
    }
  ]
}
```

### `item/delete`

Sent when an item is deleted from the team's inventory.

{% hint style="warning" %}
**Note**: This event is *not* triggered for bulk deletions made through <mark style="color:blue;">**`Data Center`**</mark>**&#x20;>&#x20;**<mark style="color:blue;">**`Item`**</mark>.
{% endhint %}

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

#### Example Payload **– Item Deleted**

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