跳转到内容
用户指南
English한국어DeutschEspañolFrançaisBahasa Indonesia日本語PortuguêsРусскийไทยTiếng Việt简体中文繁體中文

Webhook

Webhook 是一项在 BoxHero 中发生特定事件时，让您实时接收通知的功能。

注册

Section titled “注册”

您可以在 BoxHero 团队的 设置 > 集成和 API 中注册 Webhook。

发送与重试机制

Section titled “发送与重试机制”

事件发生时，BoxHero 会向您注册的 Webhook 端点发送 HTTP POST 请求。请求正文包含描述该事件的 JSON 负载。

  • 如果您的服务器返回任意 2xx 状态码（例如 200、201、204），则视为发送成功。
  • 任何 非 2xx 响应 都会被视为失败，并将进行重试。

Webhook 负载结构

Section titled “Webhook 负载结构”

所有 Webhook 事件都会以如下 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)
}

事件顺序

Section titled “事件顺序”

BoxHero 不 保证事件的发送顺序。例如，同一商品的 item/new 事件可能会在 item/delete 事件之后到达。

事件负载中的 created_time 字段表示事件的实际发生时间。请在 Webhook 处理程序中实现幂等且不依赖顺序的逻辑，以便可靠地处理事件。

事件主题

Section titled “事件主题”

txs/new

Section titled “txs/new”

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

字段必填说明
id✓交易的唯一 ID
type✓交易类型
(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 负载示例 – Stock In 事件

Section titled “Webhook 负载示例 – Stock In 事件”
{
  "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"
}

Webhook 负载示例 – Move Stock 事件

Section titled “Webhook 负载示例 – Move Stock 事件”
{
  "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

Section titled “txs/edit”

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

字段必填说明
id✓交易的唯一 ID
type✓交易类型
(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与交易相关的备注
revision✓交易的当前版本号（从 1 开始）

Webhook 负载示例 – 已编辑的 Stock In 交易

Section titled “Webhook 负载示例 – 已编辑的 Stock In 交易”
{
  "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"
}

Webhook 负载示例 – 已编辑的 Move Stock 交易

Section titled “Webhook 负载示例 – 已编辑的 Move Stock 交易”
{
  "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

Section titled “txs/delete”

在库存交易被 删除 时发送。

字段说明
id交易的唯一 ID
revision交易的当前版本号（从 1 开始）

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

Section titled “Webhook 负载示例 – 已删除的交易”
{
  "id": 27036740,
  "revision": 2
}

item/new

Section titled “item/new”

在团队库存中添加新商品时发送。

字段说明
id商品 ID
name商品名称
skuSKU
barcode条码
photo_url照片 URL
cost成本
price价格
attrs属性

负载示例 – 商品已创建

Section titled “负载示例 – 商品已创建”
{
  "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

Section titled “item/edit”

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

字段说明
id商品 ID
name商品名称
skuSKU
barcode条码
photo_url照片 URL
cost成本
price价格
attrs属性

负载示例 – 商品已更新

Section titled “负载示例 – 商品已更新”
{
  "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

Section titled “item/delete”

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

字段说明
id商品 ID

负载示例 – 商品已删除

Section titled “负载示例 – 商品已删除”
{
  "id": 26122826
}