Overview

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

Registration

You can register a webhook at Settings > Integrations 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 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:

{
  "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

txs/new

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

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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "id": 27036740,
  "revision": 2
}

item/new

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

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

{
  "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.

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

{
  "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.

Field	Description
id	Item ID

Example Payload – Item Deleted

{
  "id": 26122826
}