> For the complete documentation index, see [llms.txt](https://www.boxhero.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.boxhero.io/docs/documentation/zh/ji-cheng/webhook.md).

# Webhook

<figure><img src="/files/ff2ac61f5a4d1efe68fac38f84a5d3578a1e8e87" alt=""><figcaption></figcaption></figure>

***

## 注册

你可以在以下位置注册一个 webhook <mark style="color:蓝色;">**`设置`**</mark> **>** <mark style="color:蓝色;">**`集成与 API`**</mark> 在你的 BoxHero 团队中。

<figure><img src="/files/70e5ab0cf2096e0dcfecd09b249a3d0a9313efc7" alt=""><figcaption></figcaption></figure>

## 投递与重试行为

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

* 如果你的服务器返回 **HTTP 200 OK**，则该事件被视为已成功投递。
* 如果你的服务器返回 **任何非 200 状态码**，BoxHero 会将其视为临时失败，并最多重试投递 3 次。

## Webhook 负载结构

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

```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 处理程序中实现幂等且可容忍顺序的逻辑，以可靠地处理事件。

## 事件主题

{% hint style="info" %}
如果你需要支持更多事件主题，请联系 [支持](/docs/documentation/zh/zi-yuan/contact.md).
{% endhint %}

### `txs/new`

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

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

<table><thead><tr><th width="207">字段</th><th width="100" data-type="checkbox">必填</th><th>描述</th><th data-hidden data-type="checkbox">是否必填</th><th data-hidden>说明</th><th data-hidden>团队模式</th></tr></thead><tbody><tr><td>id</td><td>true</td><td>交易的唯一 ID</td><td>true</td><td>历史记录的唯一 ID</td><td>全部</td></tr><tr><td>type</td><td>true</td><td>交易类型\n（in，out，adjust，move）</td><td>true</td><td><p>历史记录的类型。</p><ul><li>入库：in</li><li>出库：out</li><li>调整：adjust</li><li>移动：move</li></ul></td><td>全部</td></tr><tr><td>partner</td><td>false</td><td>关联方</td><td>false</td><td></td><td></td></tr><tr><td>partner.id</td><td>false</td><td>关联方的唯一 ID</td><td>false</td><td></td><td></td></tr><tr><td>partner.name</td><td>false</td><td>关联方名称</td><td>false</td><td></td><td></td></tr><tr><td>partner.deleted</td><td>false</td><td>关联方是否已删除</td><td>false</td><td></td><td></td></tr><tr><td>from_location</td><td>false</td><td>来源位置</td><td>false</td><td></td><td></td></tr><tr><td>from_location.id</td><td>false</td><td>来源位置的唯一 ID</td><td>false</td><td></td><td></td></tr><tr><td>from_location.name</td><td>false</td><td>来源位置名称</td><td>false</td><td></td><td></td></tr><tr><td>from_location.deleted</td><td>false</td><td>来源位置是否已删除</td><td>false</td><td></td><td></td></tr><tr><td>to_location</td><td>true</td><td>目标位置</td><td>false</td><td></td><td></td></tr><tr><td>to_location.id</td><td>true</td><td>目标位置的唯一 ID</td><td>false</td><td></td><td></td></tr><tr><td>to_location.name</td><td>true</td><td>目标位置名称</td><td>false</td><td></td><td></td></tr><tr><td>to_location.deleted</td><td>true</td><td>目标位置是否已删除</td><td>false</td><td></td><td></td></tr><tr><td>items</td><td>true</td><td>交易中的明细项</td><td>true</td><td>构成历史记录的各商品项目</td><td>所有模式</td></tr><tr><td>items.id</td><td>true</td><td>商品的唯一 ID</td><td>true</td><td>商品的唯一 ID</td><td>所有模式</td></tr><tr><td>items.name</td><td>true</td><td>商品名称</td><td>true</td><td>商品名称</td><td>所有模式</td></tr><tr><td>items.quantity</td><td>true</td><td>因入库/出库/调整/移动导致的库存变动</td><td>true</td><td>该商品的入库/出库/调整/移动数量</td><td>所有模式</td></tr><tr><td>items.deleted</td><td>true</td><td>商品是否已删除</td><td>true</td><td>商品是否已删除</td><td></td></tr><tr><td>items.from_location_new_stock_level</td><td>false</td><td>交易后来源位置的库存水平</td><td>false</td><td></td><td></td></tr><tr><td>items.to_location_new_stock_level</td><td>true</td><td>交易后目标位置的库存水平</td><td>false</td><td></td><td></td></tr><tr><td>transaction_time</td><td>true</td><td>交易时间（例如入库/出库时间）</td><td>false</td><td></td><td></td></tr><tr><td>created_at</td><td>true</td><td>交易创建时间</td><td>false</td><td></td><td></td></tr><tr><td>created_by</td><td>true</td><td>创建该交易的成员</td><td>false</td><td></td><td></td></tr><tr><td>created_by.id</td><td>true</td><td>成员的唯一 ID</td><td>false</td><td></td><td></td></tr><tr><td>created_by.name</td><td>true</td><td>成员名称</td><td>false</td><td></td><td></td></tr><tr><td>created_by.deleted</td><td>true</td><td>成员是否已删除</td><td>false</td><td></td><td></td></tr><tr><td>count_of_items</td><td>true</td><td>商品数量</td><td>false</td><td></td><td></td></tr><tr><td>total_quantity</td><td>true</td><td>库存变动总量</td><td>false</td><td></td><td></td></tr><tr><td>url</td><td>true</td><td>查看交易详情页的 URL 地址</td><td>false</td><td></td><td></td></tr><tr><td>memo</td><td>false</td><td>与该交易相关的备注</td><td>false</td><td></td><td></td></tr></tbody></table>

#### 示例 Webhook 负载 – `入库` 事件

```json
{
  "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 负载 – `移动库存` 事件

<pre class="language-json"><code class="lang-json">{
  "id": 3692714,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "仓库 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "仓库 3",
<strong>    "deleted": false
</strong>  },
  "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"
}
</code></pre>

### `txs/edit`

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

<table><thead><tr><th>字段</th><th width="100" data-type="checkbox">必填</th><th>描述</th><th data-hidden data-type="checkbox">是否必填</th><th data-hidden>说明</th><th data-hidden>团队模式</th></tr></thead><tbody><tr><td>id</td><td>true</td><td>交易的唯一 ID</td><td>true</td><td>历史记录的唯一 ID</td><td>全部</td></tr><tr><td>type</td><td>true</td><td>交易类型\n（in，out，adjust，move）</td><td>true</td><td><p>历史记录的类型。</p><ul><li>入库：in</li><li>出库：out</li><li>调整：adjust</li><li>移动：move</li></ul></td><td>全部</td></tr><tr><td>partner</td><td>false</td><td>关联方</td><td>false</td><td></td><td></td></tr><tr><td>partner.id</td><td>false</td><td>关联方的唯一 ID</td><td>false</td><td></td><td></td></tr><tr><td>partner.name</td><td>false</td><td>关联方名称</td><td>false</td><td></td><td></td></tr><tr><td>partner.deleted</td><td>false</td><td>关联方是否已删除</td><td>false</td><td></td><td></td></tr><tr><td>from_location</td><td>false</td><td>来源位置</td><td>false</td><td></td><td></td></tr><tr><td>from_location.id</td><td>false</td><td>来源位置的唯一 ID</td><td>false</td><td></td><td></td></tr><tr><td>from_location.name</td><td>false</td><td>来源位置名称</td><td>false</td><td></td><td></td></tr><tr><td>from_location.deleted</td><td>false</td><td>来源位置是否已删除</td><td>false</td><td></td><td></td></tr><tr><td>to_location</td><td>true</td><td>目标位置</td><td>false</td><td></td><td></td></tr><tr><td>to_location.id</td><td>true</td><td>目标位置的唯一 ID</td><td>false</td><td></td><td></td></tr><tr><td>to_location.name</td><td>true</td><td>目标位置名称</td><td>false</td><td></td><td></td></tr><tr><td>to_location.deleted</td><td>true</td><td>目标位置是否已删除</td><td>false</td><td></td><td></td></tr><tr><td>items</td><td>true</td><td>交易中的明细项</td><td>true</td><td>构成历史记录的各商品项目</td><td>所有模式</td></tr><tr><td>items.id</td><td>true</td><td>商品的唯一 ID</td><td>true</td><td>商品的唯一 ID</td><td>所有模式</td></tr><tr><td>items.name</td><td>true</td><td>商品名称</td><td>true</td><td>商品名称</td><td>所有模式</td></tr><tr><td>items.quantity</td><td>true</td><td>因交易（in/out/adjust/move）导致的数量变更</td><td>true</td><td>该商品的入库/出库/调整/移动数量</td><td>所有模式</td></tr><tr><td>items.deleted</td><td>true</td><td>商品是否已删除</td><td>true</td><td>商品是否已删除</td><td></td></tr><tr><td>items.from_location_new_stock_level</td><td>false</td><td>交易后来源位置的库存水平</td><td>false</td><td></td><td></td></tr><tr><td>items.to_location_new_stock_level</td><td>true</td><td>交易后目标位置的库存水平</td><td>false</td><td></td><td></td></tr><tr><td>transaction_time</td><td>true</td><td>交易时间（例如入库/出库时间）</td><td>false</td><td></td><td></td></tr><tr><td>created_at</td><td>true</td><td>交易创建时间</td><td>false</td><td></td><td></td></tr><tr><td>created_by</td><td>true</td><td>创建该交易的成员</td><td>false</td><td></td><td></td></tr><tr><td>created_by.id</td><td>true</td><td>成员的唯一 ID</td><td>false</td><td></td><td></td></tr><tr><td>created_by.name</td><td>true</td><td>成员名称</td><td>false</td><td></td><td></td></tr><tr><td>created_by.deleted</td><td>true</td><td>成员是否已删除</td><td>false</td><td></td><td></td></tr><tr><td>count_of_items</td><td>true</td><td>商品数量</td><td>false</td><td></td><td></td></tr><tr><td>total_quantity</td><td>true</td><td>库存变动总量</td><td>false</td><td></td><td></td></tr><tr><td>url</td><td>true</td><td>查看交易详情页的 URL 地址</td><td>false</td><td></td><td></td></tr><tr><td>memo</td><td>false</td><td>与该交易相关的备注</td><td>false</td><td></td><td></td></tr><tr><td>修订版</td><td>true</td><td>交易的当前版本号，从 1 开始</td><td>false</td><td></td><td></td></tr></tbody></table>

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

```json
{
  "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 负载 – 已编辑的交易 `移动库存` 交易

```json
{
  "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 负载 – 已删除的交易

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

### `item/new`

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

{% hint style="warning" %}
**注意**：此事件是 *不* 在使用以下功能时触发： <mark style="color:蓝色;">**`添加商品变体`**</mark> 功能，或通过以下方式导入商品： <mark style="color:蓝色;">**`导入 Excel`**</mark>.
{% endhint %}

<table><thead><tr><th width="318">字段</th><th>描述</th><th data-hidden data-type="checkbox">是否必填</th><th data-hidden>说明</th><th data-hidden>团队模式</th></tr></thead><tbody><tr><td>id</td><td>商品 ID</td><td>true</td><td>历史记录的唯一 ID</td><td>全部</td></tr><tr><td>name</td><td>商品名称</td><td>true</td><td><p>历史记录的类型。</p><ul><li>入库：in</li><li>出库：out</li><li>调整：adjust</li><li>移动：move</li></ul></td><td>全部</td></tr><tr><td>sku</td><td>SKU</td><td>false</td><td></td><td></td></tr><tr><td>barcode</td><td>条形码</td><td>false</td><td></td><td></td></tr><tr><td>photo_url</td><td>图片 URL</td><td>false</td><td></td><td></td></tr><tr><td>cost</td><td>成本</td><td>false</td><td></td><td></td></tr><tr><td>price</td><td>价格</td><td>false</td><td></td><td></td></tr><tr><td>attrs</td><td>属性</td><td>false</td><td></td><td></td></tr></tbody></table>

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

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

### `item/edit`

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

{% hint style="warning" %}
**注意**：此事件是 *不* 触发 *f*或通过以下方式进行的批量编辑： <mark style="color:蓝色;">**`数据中心`**</mark>**&#x20;>&#x20;**<mark style="color:蓝色;">**`商品`**</mark> 或通过 <mark style="color:蓝色;">**`导入 Excel`**</mark> 功能。
{% endhint %}

<table><thead><tr><th width="318">字段</th><th>描述</th><th data-hidden data-type="checkbox">是否必填</th><th data-hidden>说明</th><th data-hidden>团队模式</th></tr></thead><tbody><tr><td>id</td><td>商品 ID</td><td>true</td><td>历史记录的唯一 ID</td><td>全部</td></tr><tr><td>name</td><td>商品名称</td><td>true</td><td><p>历史记录的类型。</p><ul><li>入库：in</li><li>出库：out</li><li>调整：adjust</li><li>移动：move</li></ul></td><td>全部</td></tr><tr><td>sku</td><td>SKU</td><td>false</td><td></td><td></td></tr><tr><td>barcode</td><td>条形码</td><td>false</td><td></td><td></td></tr><tr><td>photo_url</td><td>图片 URL</td><td>false</td><td></td><td></td></tr><tr><td>cost</td><td>成本</td><td>false</td><td></td><td></td></tr><tr><td>price</td><td>价格</td><td>false</td><td></td><td></td></tr><tr><td>attrs</td><td>属性</td><td>false</td><td></td><td></td></tr></tbody></table>

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

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

### `item/delete`

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

{% hint style="warning" %}
**注意**：此事件是 *不* 通过以下方式进行的批量删除会触发： <mark style="color:蓝色;">**`数据中心`**</mark>**&#x20;>&#x20;**<mark style="color:蓝色;">**`商品`**</mark>.
{% endhint %}

<table><thead><tr><th width="318">字段</th><th>描述</th><th data-hidden data-type="checkbox">是否必填</th><th data-hidden>说明</th><th data-hidden>团队模式</th></tr></thead><tbody><tr><td>id</td><td>商品 ID</td><td>true</td><td>历史记录的唯一 ID</td><td>全部</td></tr></tbody></table>

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

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