# Webhook

<figure><img src="/files/RVhTRqV4y9x8CR8oxB3o" 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](/docs/resources/contact.md).
{% 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
}
```


---

# 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/integrations/open-api/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.