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

Handler

When an event occurs, the event body is delivered to the registered Webhook Endpoint. If the webhook handler response status code is 200, it is judged to have been received successfully. If a non-200 status code is returned, it is considered a temporary error and retries up to 3 times.

Event Body

The following data is transferred to the POST Body in a JSON format.

{
  "id": "1234", // Event's unique ID
  "topic": "txs/new", // Event topic
  "version": 1, // Event body version
  "payload": { // Event body
    ...
  },
  "created_time": "2024-08-06T09:20:48.623Z" // The actual time when the event occurred
}

Event Order

BoxHero does not guarantee the order of event delivery. For example, an item/new event may arrive after an item/delete event. The created_time field in the event payload represents the actual time of the event occurrence. You should implement appropriate handling logic based on this field to ensure proper processing of events.

Event Topic

If you need additional topics, please contact support.

txs/new

Sent when an inventory change (in/out/adjust/move) event occurs.

Field	Required	Team Mode	Description
id		All	Transaction's unique ID
type		All	Transaction type (in, out, adjust, move)
partner		All	Partner
partner.id		All	Partner's unique ID
partner.name		All	Partner's name
partner.deleted		All	Whether the partner is deleted
from_location		Location	Departure location
from_location.id		Location	Location's unique ID
from_location.name		Location	Location name
from_location.deleted		Location	Whether the location is deleted
to_location		Location	Arrival location
to_location.id		Location	Location's unique ID
to_location.name		Location	Location name
to_location.deleted		Location	Whether the location is deleted
items		All	Line items in transaction
items.id		All	Item's unique ID
items.name		All	Item name
items.quantity		All	Inventory change due to stock in/out/adjust/move
items.deleted		All	Whether the item is deleted
items.new_stock_level		Default/Unit	The stock level after the transaction
items.from_location_new_stock_level		Location	The stock level for the departure location after the transaction
items.to_location_new_stock_level		Location	The stock level for the arrival location after the transaction
transaction_time		All	Transaction time (e.g. stock in/out time)
created_at		All	The time when the transaction was created
created_by		All	Member who created the transaction
created_by.id		All	Member's unique ID
created_by.name		All	Member name
created_by.deleted		All	Whether the member is deleted
count_of_items		All	The number of items
total_quantity		All	The total amount of inventory change
url		All	Address to go to the transaction details page
memo		All	Notes related to the transaction

Event Body Example - Stock In Event (Basic Mode)

{
  "id": 16160911,
  "type": "in",
  "items": [
    {
      "id": 14277699,
      "name": "belif Cleansing Gel Oil Enriched",
      "quantity": 2,
      "deleted": false,
      "new_stock_level": 40
    },
    {
      "id": 14277698,
      "name": "belif Aqua Bomb Jelly Cleanser",
      "quantity": 2,
      "deleted": false,
      "new_stock_level": 207
    }
  ],
  "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"
}

Event Body Example - Move Stock Event (Location Mode)

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

item/new

Sent when an item is added.

When using the ‘Add Item Variants’ feature or the ‘Import Excel’ function, webhooks are not triggered.

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

Event Body Example

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

item/edit

Sent when an item is edited.

The webhook is not triggered for bulk edits done through [Data Center] > [Item] page or when using 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

Event Body Example

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

item/delete

Sent when an item is deleted.

The webhook is not triggered for bulk deletions done through [Data Center] > [Item] page.

Field	Description
id	Item ID

Event Body Example

{
  "id": 26122826
}