# Webhook

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

***

## 注册

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

## 投递与重试行为

当事件发生时，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>交易类型<br>（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>商品</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": "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 载荷 – `转移库存` 事件

<pre class="language-json"><code class="lang-json">{
  "id": 3692714,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "Warehouse 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Warehouse 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>交易类型<br>（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>商品</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>revision</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": "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 载荷 – 已编辑 `转移库存` 交易

```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": "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`

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

{% 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>名称</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>条形码</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>成本</td><td>成本</td><td>false</td><td></td><td></td></tr><tr><td>价格</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": "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`

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

{% hint style="warning" %}
**注意**：此事件 *不会* 触发 *f*or 通过 <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>名称</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>条形码</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>成本</td><td>成本</td><td>false</td><td></td><td></td></tr><tr><td>价格</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": "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`

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

{% 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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.