Webhook

Webhook 是一种功能，可让你在 BoxHero 中发生特定事件时接收实时通知。

---

注册

你可以在以下位置注册一个 webhook 设置 > 集成与 API 在你的 BoxHero 团队中。

投递与重试行为

当事件发生时，BoxHero 会发送一个 HTTP POST 请求到你注册的 webhook 端点。请求正文包含描述该事件的 JSON 负载。

• 如果你的服务器返回 HTTP 200 OK，则该事件被视为已成功投递。

• 如果你的服务器返回 任何非 200 状态码，BoxHero 会将其视为临时失败，并最多重试投递 3 次。

Webhook 负载结构

所有 webhook 事件都会在请求正文中以以下 JSON 结构发送：

{
  "id": "1234", // 事件的唯一 ID
  "topic": "txs/new", // 事件主题
  "version": 1, // 负载架构版本
  "payload": { // 事件特定数据
    ...
  },
  "created_time": "2025-08-06T09:20:48.623Z" // 事件发生时间戳（ISO 8601）
}

---

事件顺序

BoxHero 不会 保证事件投递顺序。例如，一个 item/new 事件可能会晚于一个 item/delete 事件到达，即使它们对应的是同一个商品。

该 created_time 字段表示事件的实际发生时间。请在你的 webhook 处理程序中实现幂等且可容忍顺序的逻辑，以可靠地处理事件。

事件主题

如果你需要支持更多事件主题，请联系 支持.

txs/new

当发生库存交易时触发（入库 / 出库 / 调整库存 / 移动库存）。

注意： 此事件 不 会因通过批量编辑或导入创建的调整而触发（例如，通过 Excel 添加或更新商品时）。

必填是否必填

字段	必填	描述
id		交易的唯一 ID
type		交易类型\n（in，out，adjust，move）
partner		关联方
partner.id		关联方的唯一 ID
partner.name		关联方名称
partner.deleted		关联方是否已删除
from_location		来源位置
from_location.id		来源位置的唯一 ID
from_location.name		来源位置名称
from_location.deleted		来源位置是否已删除
to_location		目标位置
to_location.id		目标位置的唯一 ID
to_location.name		目标位置名称
to_location.deleted		目标位置是否已删除
items		交易中的明细项
items.id		商品的唯一 ID
items.name		商品名称
items.quantity		因入库/出库/调整/移动导致的库存变动
items.deleted		商品是否已删除
items.from_location_new_stock_level		交易后来源位置的库存水平
items.to_location_new_stock_level		交易后目标位置的库存水平
transaction_time		交易时间（例如入库/出库时间）
created_at		交易创建时间
created_by		创建该交易的成员
created_by.id		成员的唯一 ID
created_by.name		成员名称
created_by.deleted		成员是否已删除
count_of_items		商品数量
total_quantity		库存变动总量
url		查看交易详情页的 URL 地址
memo		与该交易相关的备注

示例 Webhook 负载 – 入库 事件

{
  "id": 16160911,
  "type": "in",
  "to_location": {
    "id": 52766,
    "name": "仓库 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"
}

示例 Webhook 负载 – 移动库存 事件

{
  "id": 3692714,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "仓库 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "仓库 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

当现有库存交易（入库 / 出库 / 调整库存 / 移动库存）被 编辑时发送.

必填是否必填

字段	必填	描述
id		交易的唯一 ID
type		交易类型\n（in，out，adjust，move）
partner		关联方
partner.id		关联方的唯一 ID
partner.name		关联方名称
partner.deleted		关联方是否已删除
from_location		来源位置
from_location.id		来源位置的唯一 ID
from_location.name		来源位置名称
from_location.deleted		来源位置是否已删除
to_location		目标位置
to_location.id		目标位置的唯一 ID
to_location.name		目标位置名称
to_location.deleted		目标位置是否已删除
items		交易中的明细项
items.id		商品的唯一 ID
items.name		商品名称
items.quantity		因交易（in/out/adjust/move）导致的数量变更
items.deleted		商品是否已删除
items.from_location_new_stock_level		交易后来源位置的库存水平
items.to_location_new_stock_level		交易后目标位置的库存水平
transaction_time		交易时间（例如入库/出库时间）
created_at		交易创建时间
created_by		创建该交易的成员
created_by.id		成员的唯一 ID
created_by.name		成员名称
created_by.deleted		成员是否已删除
count_of_items		商品数量
total_quantity		库存变动总量
url		查看交易详情页的 URL 地址
memo		与该交易相关的备注
修订版		交易的当前版本号，从 1 开始

示例 Webhook 负载 – 已编辑的交易 入库 交易

{
  "id": 16160911,
  "type": "in",
  "to_location": {
    "id": 52766,
    "name": "仓库 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"
}

示例 Webhook 负载 – 已编辑的交易 移动库存 交易

{
  "id": 3692714,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "仓库 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "仓库 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

当库存交易被 删除时发送.

字段	描述
id	交易的唯一 ID
修订版	交易的当前版本号，从 1 开始

示例 Webhook 负载 – 已删除的交易

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

item/new

当新商品添加到团队库存时发送。

注意：此事件是 不 在使用以下功能时触发： 添加商品变体 功能，或通过以下方式导入商品： 导入 Excel.

是否必填

字段	描述
id	商品 ID
name	商品名称
sku	SKU
barcode	条形码
photo_url	图片 URL
cost	成本
price	价格
attrs	属性

示例负载 – 商品已创建

{
  "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": "类别",
      "type": "text",
      "value": "粉底"
    },
    {
      "id": 459264,
      "name": "到期日期",
      "type": "date",
      "value": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "安全库存",
      "type": "number",
      "value": 33
    }
  ]
}

item/edit

当现有商品被编辑时发送。

注意：此事件是 不 触发 f或通过以下方式进行的批量编辑： 数据中心 > 商品 或通过 导入 Excel 功能。

是否必填

字段	描述
id	商品 ID
name	商品名称
sku	SKU
barcode	条形码
photo_url	图片 URL
cost	成本
price	价格
attrs	属性

示例负载 – 商品已更新

{
  "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": "类别",
      "type": "text",
      "value": "粉底"
    },
    {
      "id": 459264,
      "name": "到期日期",
      "type": "date",
      "value": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "安全库存",
      "type": "number",
      "value": 33
    }
  ]
}

item/delete

当商品从团队库存中删除时发送。

注意：此事件是 不 通过以下方式进行的批量删除会触发： 数据中心 > 商品.

字段	描述
id	商品 ID

示例负载 – 商品已删除

{
  "id": 26122826
}