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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://www.boxhero.io/docs/documentation/zh/ji-cheng/webhook.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.