> For the complete documentation index, see [llms.txt](https://www.boxhero.io/docs/llms.txt). Every page is available as Markdown by appending `.md` to its URL; this page is [Markdown](https://www.boxhero.io/docs/zh-cn/integrations/webhook.md).

# Webhook

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

![](https://assets.boxhero.io/docs/images/e073efd69a551d1c50313ce8969f89656fe7fb6c2f4bf97cd67eb7398f4e21d6-1601x941.jpeg)

---

## 注册

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

![](https://assets.boxhero.io/docs/images/39738e2bf18459a1ba1d9df4c6a3eb786fc434f5fab37932e8edf50bf6a0b91a-1100x810.png)

## 发送与重试机制

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

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

## Webhook 负载结构

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

```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)
}
```

---

## 事件顺序

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

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

## 事件主题

> **Note**
>
> 如需支持其他事件主题，请[联系我们](https://www.boxhero.io/docs/zh-cn/resources/contact)。

### txs/new

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

> **Caution**
>
> **注意：** 通过批量编辑或导入（例如通过 Excel 添加或更新商品）产生的调整 _不会_ 触发此事件。

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| 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 事件

```json
{
  "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 事件

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

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

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| 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 交易

```json
{
  "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 交易

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

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

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

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

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

### item/new

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

> **Caution**
>
> **注意**：使用 `添加商品变体` 功能或通过 `导入 Excel` 导入商品时，_不会_ 触发此事件。

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

#### 负载示例 – 商品已创建

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

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

> **Caution**
>
> **注意**：通过 `数据中心` > `商品` 或 `导入 Excel` 功能进行的批量编辑 _不会_ 触发此事件。

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

#### 负载示例 – 商品已更新

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

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

> **Caution**
>
> **注意**：通过 `数据中心` > `商品` 进行的批量删除 _不会_ 触发此事件。

| 字段 | 说明 |
| --- | --- |
| id | 商品 ID |

#### 负载示例 – 商品已删除

```json
{
  "id": 26122826
}
```