Webhook

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

---

Registration

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

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

If you need support for additional event topics, please contact Support.

txs/new

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

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

Required필수여부

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 / Adjust Stock / Move Stock) is edited.

Required필수여부

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

Note: This event is not triggered when using the Add Item Variants feature or importing items via Import 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

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

Note: This event is not triggered for bulk edits made through Data Center > Item or via the Import 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

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

Note: This event is not triggered for bulk deletions made through Data Center > Item.

Field	Description
id	Item ID

Example Payload – Item Deleted

{
  "id": 26122826
}