> For the complete documentation index, see [llms.txt](https://www.boxhero.io/docs/llms.txt). Every page is available as Markdown by appending `.md` to its URL; this page is [Markdown](https://www.boxhero.io/docs/developers/webhooks/overview.md).

# Overview

> Webhooks are a feature that allows you to receive real-time notifications when certain events occur in BoxHero.

![](https://assets.boxhero.io/docs/images/e073efd69a551d1c50313ce8969f89656fe7fb6c2f4bf97cd67eb7398f4e21d6-1601x941.jpeg)

---

## Registration

You can register a webhook at `Settings` > `Integrations` in your BoxHero team.

![](https://assets.boxhero.io/docs/images/39738e2bf18459a1ba1d9df4c6a3eb786fc434f5fab37932e8edf50bf6a0b91a-1100x810.png)

## 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 any **2xx status code** (e.g., 200, 201, 204), the delivery is treated as successful.
- Any **non-2xx response** is considered a failure and will be retried.

## Webhook Payload Structure

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

```json
{
  "id": "3f9a2b7c-6d4e-4a1f-9c8b-2e5d7a0f1b34", // 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.

Events for edited and deleted transactions (`txs/edit`, `txs/delete`) also carry `revision`, so you can tell which version of a transaction an event describes.

## Event Topics

> **Note**
>
> If you need support for additional event topics, please contact [Support](https://www.boxhero.io/docs/resources/contact).

### txs/new

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

> **Caution**
>
> **Note:** This event is _not_ triggered for adjustments created through bulk edits or imports (e.g., when adding or updating items via Excel).

| Field | Required | Description |
| --- | --- | --- |
| id | ✓ | Transaction's unique ID |
| type | ✓ | Transaction type (in, out, adjust, move) |
| partner |  | Partner |
| partner.id |  | Partner's unique ID |
| partner.name |  | Partner's name |
| partner.deleted |  | Whether the partner is deleted |
| from_location |  | Source location |
| from_location.id |  | Source location's unique ID |
| from_location.name |  | Source location name |
| from_location.deleted |  | Whether the source location is deleted |
| to_location | ✓ | Destination location |
| to_location.id | ✓ | Destination location's unique ID |
| to_location.name | ✓ | Destination location name |
| to_location.deleted | ✓ | Whether the destination location is deleted |
| items | ✓ | Line items in transaction |
| items.id | ✓ | Item's unique ID |
| items.name | ✓ | Item name |
| items.quantity | ✓ | Inventory change due to stock in/out/adjust/move |
| items.deleted | ✓ | Whether the item is deleted |
| items.from_location_new_stock_level |  | The stock level at source location after the transaction |
| items.to_location_new_stock_level | ✓ | The stock level at destination location after the transaction |
| transaction_time | ✓ | Transaction time (e.g. stock in/out time) |
| created_at | ✓ | The time when the transaction was created |
| created_by | ✓ | Member who created the transaction |
| created_by.id | ✓ | Member's unique ID |
| created_by.name | ✓ | Member name |
| created_by.deleted | ✓ | Whether the member is deleted |
| count_of_items | ✓ | The number of items |
| total_quantity | ✓ | The total amount of inventory change |
| url | ✓ | URL address to view the transaction details page |
| memo |  | Notes related to the transaction |

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

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

### txs/edit

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

| Field | Required | Description |
| --- | --- | --- |
| id | ✓ | Transaction's unique ID |
| type | ✓ | Transaction type (in, out, adjust, move) |
| partner |  | Partner |
| partner.id |  | Partner's unique ID |
| partner.name |  | Partner's name |
| partner.deleted |  | Whether the partner is deleted |
| from_location |  | Source location |
| from_location.id |  | Source location's unique ID |
| from_location.name |  | Source location name |
| from_location.deleted |  | Whether the source location is deleted |
| to_location | ✓ | Destination location |
| to_location.id | ✓ | Destination location's unique ID |
| to_location.name | ✓ | Destination location name |
| to_location.deleted | ✓ | Whether the destination location is deleted |
| items | ✓ | Line items in transaction |
| items.id | ✓ | Item's unique ID |
| items.name | ✓ | Item name |
| items.quantity | ✓ | Quantity change due to transaction (in/out/adjust/move) |
| items.deleted | ✓ | Whether the item is deleted |
| items.from_location_new_stock_level |  | The stock level at source location after the transaction |
| items.to_location_new_stock_level | ✓ | The stock level at destination location after the transaction |
| transaction_time | ✓ | Transaction time (e.g. stock in/out time) |
| created_at | ✓ | The time when the transaction was created |
| created_by | ✓ | Member who created the transaction |
| created_by.id | ✓ | Member's unique ID |
| created_by.name | ✓ | Member name |
| created_by.deleted | ✓ | Whether the member is deleted |
| count_of_items | ✓ | The number of items |
| total_quantity | ✓ | The total amount of inventory change |
| url | ✓ | URL address to view the transaction details page |
| memo |  | Notes related to the transaction |
| revision | ✓ | Current version number of the transaction, starting from 1 |

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

```json
{
  "id": 16160911,
  "revision": 2,
  "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,
  "revision": 2,
  "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.

> **Caution**
>
> **Note**: This event is _not_ triggered when using the `Add Item Variants` feature or importing items via `Import from Excel`.

| Field | Description |
| --- | --- |
| id | Item ID |
| name | Item Name |
| sku | SKU |
| barcode | Barcode |
| photo_url | Photo URL |
| cost | Cost |
| price | Price |
| attrs | Attributes |

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

> **Caution**
>
> **Note**: This event is _not_ triggered for bulk edits made through `Data Center` > `Item` or via the `Import from Excel` function.

| Field | Description |
| --- | --- |
| id | Item ID |
| name | Item Name |
| sku | SKU |
| barcode | Barcode |
| photo_url | Photo URL |
| cost | Cost |
| price | Price |
| attrs | Attributes |

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

> **Caution**
>
> **Note**: This event is _not_ triggered for bulk deletions made through `Data Center` > `Items`.

| Field | Description |
| --- | --- |
| id | Item ID |

#### Example Payload – Item Deleted

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