# Webhook

<figure><img src="https://3280366400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlRf1QqJGoevCQqGbfI80%2Fuploads%2Fgit-blob-094f1326e4f5b66d3f4de825a63e55cbf0f4ac01%2Fboxhero-add-webhook.png?alt=media" alt=""><figcaption></figcaption></figure>

***

## Đăng ký

Bạn có thể đăng ký webhook tại <mark style="color:màu xanh;">**`Cài đặt`**</mark> **>** <mark style="color:màu xanh;">**`Tích hợp & API`**</mark> trong đội BoxHero của bạn.

## Hành vi gửi và thử lại

Khi một sự kiện xảy ra, BoxHero gửi một HTTP `POST` request đến endpoint webhook đã đăng ký của bạn. Phần thân request chứa một payload JSON mô tả sự kiện.

* Nếu máy chủ của bạn phản hồi với **HTTP 200 OK**, sự kiện được coi là đã gửi thành công.
* Nếu máy chủ của bạn phản hồi với **bất kỳ mã trạng thái không phải 200 nào**, BoxHero xem đó là lỗi tạm thời và thử gửi lại tối đa 3 lần.

## Cấu trúc payload webhook

Tất cả các sự kiện webhook được gửi với cấu trúc JSON sau trong phần thân request:

```json
{
  "id": "1234", // ID duy nhất của sự kiện
  "topic": "txs/new", // Chủ đề sự kiện
  "version": 1, // Phiên bản schema của payload
  "payload": { // Dữ liệu riêng của sự kiện
    ...
  },
  "created_time": "2025-08-06T09:20:48.623Z" // Thời điểm sự kiện xảy ra (ISO 8601)
}
```

***

## Thứ tự sự kiện

BoxHero **không** đảm bảo thứ tự gửi sự kiện. Ví dụ, một sự kiện `item/new` có thể đến sau một sự kiện `item/delete` cho cùng một mặt hàng.

Tính năng `created_time` trong payload sự kiện biểu thị thời điểm thực tế của sự kiện. Hãy triển khai logic idempotent và chịu được thứ tự trong trình xử lý webhook của bạn để xử lý sự kiện một cách đáng tin cậy.

## Các chủ đề sự kiện

{% hint style="info" %}
Nếu bạn cần hỗ trợ thêm các chủ đề sự kiện khác, vui lòng liên hệ [Hỗ trợ](https://www.boxhero.io/docs/documentation/vi/tai-nguyen/contact).
{% endhint %}

### `txs/new`

Được kích hoạt khi xảy ra một giao dịch tồn kho (Nhập kho / Xuất kho / Điều chỉnh tồn kho / Chuyển kho).

{% hint style="warning" %}
**Lưu ý:** Sự kiện này *không* được kích hoạt đối với các điều chỉnh được tạo thông qua chỉnh sửa hàng loạt hoặc nhập dữ liệu (ví dụ: khi thêm hoặc cập nhật mặt hàng qua Excel).
{% endhint %}

<table><thead><tr><th width="207">Trường</th><th width="100" data-type="checkbox">Bắt buộc</th><th>Mô tả</th><th data-hidden data-type="checkbox">Có bắt buộc không</th><th data-hidden>Mô tả</th><th data-hidden>Chế độ đội</th></tr></thead><tbody><tr><td>id</td><td>true</td><td>ID duy nhất của giao dịch</td><td>true</td><td>ID duy nhất của lịch sử</td><td>Tất cả</td></tr><tr><td>type</td><td>true</td><td>Loại giao dịch<br>(in, out, adjust, move)</td><td>true</td><td><p>Loại của lịch sử.</p><ul><li>Nhập kho: in</li><li>Xuất kho: out</li><li>Điều chỉnh: adjust</li><li>Chuyển: move</li></ul></td><td>Tất cả</td></tr><tr><td>đối tác</td><td>false</td><td>Đối tác</td><td>false</td><td></td><td></td></tr><tr><td>partner.id</td><td>false</td><td>ID duy nhất của đối tác</td><td>false</td><td></td><td></td></tr><tr><td>partner.name</td><td>false</td><td>Tên đối tác</td><td>false</td><td></td><td></td></tr><tr><td>partner.deleted</td><td>false</td><td>Đối tác có bị xóa hay không</td><td>false</td><td></td><td></td></tr><tr><td>from_location</td><td>false</td><td>Vị trí nguồn</td><td>false</td><td></td><td></td></tr><tr><td>from_location.id</td><td>false</td><td>ID duy nhất của vị trí nguồn</td><td>false</td><td></td><td></td></tr><tr><td>from_location.name</td><td>false</td><td>Tên vị trí nguồn</td><td>false</td><td></td><td></td></tr><tr><td>from_location.deleted</td><td>false</td><td>Vị trí nguồn có bị xóa hay không</td><td>false</td><td></td><td></td></tr><tr><td>to_location</td><td>true</td><td>Vị trí đích</td><td>false</td><td></td><td></td></tr><tr><td>to_location.id</td><td>true</td><td>ID duy nhất của vị trí đích</td><td>false</td><td></td><td></td></tr><tr><td>to_location.name</td><td>true</td><td>Tên vị trí đích</td><td>false</td><td></td><td></td></tr><tr><td>to_location.deleted</td><td>true</td><td>Vị trí đích có bị xóa hay không</td><td>false</td><td></td><td></td></tr><tr><td>items</td><td>true</td><td>Các dòng hàng trong giao dịch</td><td>true</td><td>Các mục theo từng sản phẩm cấu thành lịch sử</td><td>Tất cả các chế độ</td></tr><tr><td>items.id</td><td>true</td><td>ID duy nhất của mặt hàng</td><td>true</td><td>ID duy nhất của sản phẩm</td><td>Tất cả các chế độ</td></tr><tr><td>items.name</td><td>true</td><td>Tên mặt hàng</td><td>true</td><td>Tên sản phẩm</td><td>Tất cả các chế độ</td></tr><tr><td>items.quantity</td><td>true</td><td>Thay đổi tồn kho do nhập/xuất/điều chỉnh/chuyển</td><td>true</td><td>Số lượng nhập/xuất/điều chỉnh/chuyển của sản phẩm đó</td><td>Tất cả các chế độ</td></tr><tr><td>items.deleted</td><td>true</td><td>Mặt hàng có bị xóa hay không</td><td>true</td><td>Sản phẩm đã bị xóa hay chưa</td><td></td></tr><tr><td>items.from_location_new_stock_level</td><td>false</td><td>Mức tồn kho tại vị trí nguồn sau giao dịch</td><td>false</td><td></td><td></td></tr><tr><td>items.to_location_new_stock_level</td><td>true</td><td>Mức tồn kho tại vị trí đích sau giao dịch</td><td>false</td><td></td><td></td></tr><tr><td>transaction_time</td><td>true</td><td>Thời gian giao dịch (ví dụ: thời điểm nhập/xuất kho)</td><td>false</td><td></td><td></td></tr><tr><td>created_at</td><td>true</td><td>Thời điểm giao dịch được tạo</td><td>false</td><td></td><td></td></tr><tr><td>created_by</td><td>true</td><td>Thành viên đã tạo giao dịch</td><td>false</td><td></td><td></td></tr><tr><td>created_by.id</td><td>true</td><td>ID duy nhất của thành viên</td><td>false</td><td></td><td></td></tr><tr><td>created_by.name</td><td>true</td><td>Tên thành viên</td><td>false</td><td></td><td></td></tr><tr><td>created_by.deleted</td><td>true</td><td>Thành viên có bị xóa hay không</td><td>false</td><td></td><td></td></tr><tr><td>count_of_items</td><td>true</td><td>Số lượng mặt hàng</td><td>false</td><td></td><td></td></tr><tr><td>total_quantity</td><td>true</td><td>Tổng số lượng thay đổi tồn kho</td><td>false</td><td></td><td></td></tr><tr><td>url</td><td>true</td><td>Địa chỉ URL để xem trang chi tiết giao dịch</td><td>false</td><td></td><td></td></tr><tr><td>memo</td><td>false</td><td>Ghi chú liên quan đến giao dịch</td><td>false</td><td></td><td></td></tr></tbody></table>

#### Ví dụ payload webhook – `Nhập kho` Sự kiện

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

#### Ví dụ payload webhook – `Chuyển kho` Sự kiện

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

Được gửi khi một giao dịch tồn kho hiện có (Nhập kho / Xuất kho / Điều chỉnh tồn kho / Chuyển kho) được **chỉnh sửa**.

<table><thead><tr><th>Trường</th><th width="100" data-type="checkbox">Bắt buộc</th><th>Mô tả</th><th data-hidden data-type="checkbox">Có bắt buộc không</th><th data-hidden>Mô tả</th><th data-hidden>Chế độ đội</th></tr></thead><tbody><tr><td>id</td><td>true</td><td>ID duy nhất của giao dịch</td><td>true</td><td>ID duy nhất của lịch sử</td><td>Tất cả</td></tr><tr><td>type</td><td>true</td><td>Loại giao dịch<br>(in, out, adjust, move)</td><td>true</td><td><p>Loại của lịch sử.</p><ul><li>Nhập kho: in</li><li>Xuất kho: out</li><li>Điều chỉnh: adjust</li><li>Chuyển: move</li></ul></td><td>Tất cả</td></tr><tr><td>đối tác</td><td>false</td><td>Đối tác</td><td>false</td><td></td><td></td></tr><tr><td>partner.id</td><td>false</td><td>ID duy nhất của đối tác</td><td>false</td><td></td><td></td></tr><tr><td>partner.name</td><td>false</td><td>Tên đối tác</td><td>false</td><td></td><td></td></tr><tr><td>partner.deleted</td><td>false</td><td>Đối tác có bị xóa hay không</td><td>false</td><td></td><td></td></tr><tr><td>from_location</td><td>false</td><td>Vị trí nguồn</td><td>false</td><td></td><td></td></tr><tr><td>from_location.id</td><td>false</td><td>ID duy nhất của vị trí nguồn</td><td>false</td><td></td><td></td></tr><tr><td>from_location.name</td><td>false</td><td>Tên vị trí nguồn</td><td>false</td><td></td><td></td></tr><tr><td>from_location.deleted</td><td>false</td><td>Vị trí nguồn có bị xóa hay không</td><td>false</td><td></td><td></td></tr><tr><td>to_location</td><td>true</td><td>Vị trí đích</td><td>false</td><td></td><td></td></tr><tr><td>to_location.id</td><td>true</td><td>ID duy nhất của vị trí đích</td><td>false</td><td></td><td></td></tr><tr><td>to_location.name</td><td>true</td><td>Tên vị trí đích</td><td>false</td><td></td><td></td></tr><tr><td>to_location.deleted</td><td>true</td><td>Vị trí đích có bị xóa hay không</td><td>false</td><td></td><td></td></tr><tr><td>items</td><td>true</td><td>Các dòng hàng trong giao dịch</td><td>true</td><td>Các mục theo từng sản phẩm cấu thành lịch sử</td><td>Tất cả các chế độ</td></tr><tr><td>items.id</td><td>true</td><td>ID duy nhất của mặt hàng</td><td>true</td><td>ID duy nhất của sản phẩm</td><td>Tất cả các chế độ</td></tr><tr><td>items.name</td><td>true</td><td>Tên mặt hàng</td><td>true</td><td>Tên sản phẩm</td><td>Tất cả các chế độ</td></tr><tr><td>items.quantity</td><td>true</td><td>Thay đổi số lượng do giao dịch (in/out/adjust/move)</td><td>true</td><td>Số lượng nhập/xuất/điều chỉnh/chuyển của sản phẩm đó</td><td>Tất cả các chế độ</td></tr><tr><td>items.deleted</td><td>true</td><td>Mặt hàng có bị xóa hay không</td><td>true</td><td>Sản phẩm đã bị xóa hay chưa</td><td></td></tr><tr><td>items.from_location_new_stock_level</td><td>false</td><td>Mức tồn kho tại vị trí nguồn sau giao dịch</td><td>false</td><td></td><td></td></tr><tr><td>items.to_location_new_stock_level</td><td>true</td><td>Mức tồn kho tại vị trí đích sau giao dịch</td><td>false</td><td></td><td></td></tr><tr><td>transaction_time</td><td>true</td><td>Thời gian giao dịch (ví dụ: thời điểm nhập/xuất kho)</td><td>false</td><td></td><td></td></tr><tr><td>created_at</td><td>true</td><td>Thời điểm giao dịch được tạo</td><td>false</td><td></td><td></td></tr><tr><td>created_by</td><td>true</td><td>Thành viên đã tạo giao dịch</td><td>false</td><td></td><td></td></tr><tr><td>created_by.id</td><td>true</td><td>ID duy nhất của thành viên</td><td>false</td><td></td><td></td></tr><tr><td>created_by.name</td><td>true</td><td>Tên thành viên</td><td>false</td><td></td><td></td></tr><tr><td>created_by.deleted</td><td>true</td><td>Thành viên có bị xóa hay không</td><td>false</td><td></td><td></td></tr><tr><td>count_of_items</td><td>true</td><td>Số lượng mặt hàng</td><td>false</td><td></td><td></td></tr><tr><td>total_quantity</td><td>true</td><td>Tổng số lượng thay đổi tồn kho</td><td>false</td><td></td><td></td></tr><tr><td>url</td><td>true</td><td>Địa chỉ URL để xem trang chi tiết giao dịch</td><td>false</td><td></td><td></td></tr><tr><td>memo</td><td>false</td><td>Ghi chú liên quan đến giao dịch</td><td>false</td><td></td><td></td></tr><tr><td>revision</td><td>true</td><td>Số phiên bản hiện tại của giao dịch, bắt đầu từ 1</td><td>false</td><td></td><td></td></tr></tbody></table>

#### Ví dụ payload webhook – Đã chỉnh sửa `Nhập kho` Giao dịch

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

```

#### Ví dụ payload webhook – Đã chỉnh sửa `Chuyển kho` Giao dịch

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

Được gửi khi một giao dịch tồn kho bị **xóa**.

| Trường   | Mô tả                                             |
| -------- | ------------------------------------------------- |
| id       | ID duy nhất của giao dịch                         |
| revision | Số phiên bản hiện tại của giao dịch, bắt đầu từ 1 |

#### Ví dụ payload webhook – Giao dịch đã xóa

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

### `item/new`

Được gửi khi một mặt hàng mới được thêm vào kho của đội.

{% hint style="warning" %}
**Lưu ý**: Sự kiện này *không* được kích hoạt khi sử dụng <mark style="color:màu xanh;">**`Thêm biến thể mặt hàng`**</mark> tính năng hoặc nhập mặt hàng qua <mark style="color:màu xanh;">**`Import Excel`**</mark>.
{% endhint %}

<table><thead><tr><th width="318">Trường</th><th>Mô tả</th><th data-hidden data-type="checkbox">Có bắt buộc không</th><th data-hidden>Mô tả</th><th data-hidden>Chế độ đội</th></tr></thead><tbody><tr><td>id</td><td>ID mặt hàng</td><td>true</td><td>ID duy nhất của lịch sử</td><td>Tất cả</td></tr><tr><td>name</td><td>Tên mặt hàng</td><td>true</td><td><p>Loại của lịch sử.</p><ul><li>Nhập kho: in</li><li>Xuất kho: out</li><li>Điều chỉnh: adjust</li><li>Chuyển: move</li></ul></td><td>Tất cả</td></tr><tr><td>sku</td><td>SKU</td><td>false</td><td></td><td></td></tr><tr><td>máy quét</td><td>Mã vạch</td><td>false</td><td></td><td></td></tr><tr><td>photo_url</td><td>URL ảnh</td><td>false</td><td></td><td></td></tr><tr><td>cost</td><td>Giá vốn</td><td>false</td><td></td><td></td></tr><tr><td>price</td><td>Giá</td><td>false</td><td></td><td></td></tr><tr><td>attrs</td><td>Thuộc tính</td><td>false</td><td></td><td></td></tr></tbody></table>

#### **Ví dụ payload – Mặt hàng được tạo**

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

Được gửi khi một mặt hàng hiện có được chỉnh sửa.

{% hint style="warning" %}
**Lưu ý**: Sự kiện này *không* được kích hoạt *f*hoặc <mark style="color:màu xanh;">**`Trung tâm dữ liệu`**</mark>**&#x20;>&#x20;**<mark style="color:màu xanh;">**`Item`**</mark> hoặc qua <mark style="color:màu xanh;">**`Import Excel`**</mark> chức năng.
{% endhint %}

<table><thead><tr><th width="318">Trường</th><th>Mô tả</th><th data-hidden data-type="checkbox">Có bắt buộc không</th><th data-hidden>Mô tả</th><th data-hidden>Chế độ đội</th></tr></thead><tbody><tr><td>id</td><td>ID mặt hàng</td><td>true</td><td>ID duy nhất của lịch sử</td><td>Tất cả</td></tr><tr><td>name</td><td>Tên mặt hàng</td><td>true</td><td><p>Loại của lịch sử.</p><ul><li>Nhập kho: in</li><li>Xuất kho: out</li><li>Điều chỉnh: adjust</li><li>Chuyển: move</li></ul></td><td>Tất cả</td></tr><tr><td>sku</td><td>SKU</td><td>false</td><td></td><td></td></tr><tr><td>máy quét</td><td>Mã vạch</td><td>false</td><td></td><td></td></tr><tr><td>photo_url</td><td>URL ảnh</td><td>false</td><td></td><td></td></tr><tr><td>cost</td><td>Giá vốn</td><td>false</td><td></td><td></td></tr><tr><td>price</td><td>Giá</td><td>false</td><td></td><td></td></tr><tr><td>attrs</td><td>Thuộc tính</td><td>false</td><td></td><td></td></tr></tbody></table>

#### **Ví dụ payload – Mặt hàng đã cập nhật**

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

Được gửi khi một mặt hàng bị xóa khỏi kho của đội.

{% hint style="warning" %}
**Lưu ý**: Sự kiện này *không* được kích hoạt cho các xóa hàng loạt được thực hiện qua <mark style="color:màu xanh;">**`Trung tâm dữ liệu`**</mark>**&#x20;>&#x20;**<mark style="color:màu xanh;">**`Item`**</mark>.
{% endhint %}

<table><thead><tr><th width="318">Trường</th><th>Mô tả</th><th data-hidden data-type="checkbox">Có bắt buộc không</th><th data-hidden>Mô tả</th><th data-hidden>Chế độ đội</th></tr></thead><tbody><tr><td>id</td><td>ID mặt hàng</td><td>true</td><td>ID duy nhất của lịch sử</td><td>Tất cả</td></tr></tbody></table>

#### Ví dụ payload **– Mặt hàng đã xóa**

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