> 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/vi/integrations/webhook.md).

# Webhook

> Webhook là tính năng cho phép bạn nhận thông báo theo thời gian thực khi một số sự kiện nhất định xảy ra trong BoxHero.

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

---

## Đăng ký

Bạn có thể đăng ký webhook tại `Cài đặt` > `Tích hợp` trong nhóm BoxHero của bạn.

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

## Cách gửi và thử lại

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

- Nếu máy chủ của bạn phản hồi bằng bất kỳ **mã trạng thái 2xx** nào (ví dụ: 200, 201, 204), việc gửi được xem là thành công.
- Mọi **phản hồi không phải 2xx** đều được xem là thất bại và sẽ được gửi lại.

## Cấu trúc payload webhook

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

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

---

## Thứ tự sự kiện

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

Trường `created_time` trong payload sự kiện thể hiện thời điểm thực tế xảy ra sự kiện. Hãy triển khai logic idempotent và không phụ thuộc vào thứ tự trong trình xử lý webhook để xử lý sự kiện một cách đáng tin cậy.

## Chủ đề sự kiện

> **Note**
>
> Nếu bạn cần hỗ trợ thêm các chủ đề sự kiện khác, vui lòng [liên hệ](https://www.boxhero.io/docs/vi/resources/contact) với chúng tôi.

### txs/new

Được kích hoạt khi phát sinh giao dịch tồn kho (Nhập kho / Xuất kho / Điều chỉnh / Chuyển kho).

> **Caution**
>
> **Lưu ý:** Sự kiện này _không_ được kích hoạt với các điều chỉnh được tạo 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).

| Trường | Bắt buộc | Mô tả |
| --- | --- | --- |
| id | ✓ | ID duy nhất của giao dịch |
| type | ✓ | Loại giao dịch (in, out, adjust, move) |
| partner |  | Đối tác |
| partner.id |  | ID duy nhất của đối tác |
| partner.name |  | Tên đối tác |
| partner.deleted |  | Đối tác đã bị xóa hay chưa |
| from_location |  | Vị trí nguồn |
| from_location.id |  | ID duy nhất của vị trí nguồn |
| from_location.name |  | Tên vị trí nguồn |
| from_location.deleted |  | Vị trí nguồn đã bị xóa hay chưa |
| to_location | ✓ | Vị trí đích |
| to_location.id | ✓ | ID duy nhất của vị trí đích |
| to_location.name | ✓ | Tên vị trí đích |
| to_location.deleted | ✓ | Vị trí đích đã bị xóa hay chưa |
| items | ✓ | Danh sách mặt hàng trong giao dịch |
| items.id | ✓ | ID duy nhất của mặt hàng |
| items.name | ✓ | Tên mặt hàng |
| items.quantity | ✓ | Lượng tồn kho thay đổi do nhập kho/xuất kho/điều chỉnh/chuyển kho |
| items.deleted | ✓ | Mặt hàng đã bị xóa hay chưa |
| items.from_location_new_stock_level |  | Mức tồn kho tại vị trí nguồn sau giao dịch |
| items.to_location_new_stock_level | ✓ | Mức tồn kho tại vị trí đích sau giao dịch |
| transaction_time | ✓ | Thời gian giao dịch (ví dụ: thời gian nhập/xuất kho) |
| created_at | ✓ | Thời điểm giao dịch được tạo |
| created_by | ✓ | Thành viên đã tạo giao dịch |
| created_by.id | ✓ | ID duy nhất của thành viên |
| created_by.name | ✓ | Tên thành viên |
| created_by.deleted | ✓ | Thành viên đã bị xóa hay chưa |
| count_of_items | ✓ | Số lượng mặt hàng |
| total_quantity | ✓ | Tổng lượng tồn kho thay đổi |
| url | ✓ | Địa chỉ URL để xem trang chi tiết giao dịch |
| memo |  | Ghi chú liên quan đến giao dịch |

#### Ví dụ payload webhook – Sự kiện 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"
}
```

#### Ví dụ payload webhook – Sự kiện 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

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

| Trường | Bắt buộc | Mô tả |
| --- | --- | --- |
| id | ✓ | ID duy nhất của giao dịch |
| type | ✓ | Loại giao dịch (in, out, adjust, move) |
| partner |  | Đối tác |
| partner.id |  | ID duy nhất của đối tác |
| partner.name |  | Tên đối tác |
| partner.deleted |  | Đối tác đã bị xóa hay chưa |
| from_location |  | Vị trí nguồn |
| from_location.id |  | ID duy nhất của vị trí nguồn |
| from_location.name |  | Tên vị trí nguồn |
| from_location.deleted |  | Vị trí nguồn đã bị xóa hay chưa |
| to_location | ✓ | Vị trí đích |
| to_location.id | ✓ | ID duy nhất của vị trí đích |
| to_location.name | ✓ | Tên vị trí đích |
| to_location.deleted | ✓ | Vị trí đích đã bị xóa hay chưa |
| items | ✓ | Danh sách mặt hàng trong giao dịch |
| items.id | ✓ | ID duy nhất của mặt hàng |
| items.name | ✓ | Tên mặt hàng |
| items.quantity | ✓ | Số lượng thay đổi do giao dịch (in/out/adjust/move) |
| items.deleted | ✓ | Mặt hàng đã bị xóa hay chưa |
| items.from_location_new_stock_level |  | Mức tồn kho tại vị trí nguồn sau giao dịch |
| items.to_location_new_stock_level | ✓ | Mức tồn kho tại vị trí đích sau giao dịch |
| transaction_time | ✓ | Thời gian giao dịch (ví dụ: thời gian nhập/xuất kho) |
| created_at | ✓ | Thời điểm giao dịch được tạo |
| created_by | ✓ | Thành viên đã tạo giao dịch |
| created_by.id | ✓ | ID duy nhất của thành viên |
| created_by.name | ✓ | Tên thành viên |
| created_by.deleted | ✓ | Thành viên đã bị xóa hay chưa |
| count_of_items | ✓ | Số lượng mặt hàng |
| total_quantity | ✓ | Tổng lượng tồn kho thay đổi |
| url | ✓ | Địa chỉ URL để xem trang chi tiết giao dịch |
| memo |  | Ghi chú liên quan đến 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 Stock In đã chỉnh sửa

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

```

#### Ví dụ payload webhook – Giao dịch Move Stock đã chỉnh sửa

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

Đượ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 tồn kho của nhóm.

> **Caution**
>
> **Lưu ý**: Sự kiện này _không_ được kích hoạt khi sử dụng tính năng `Thêm biến thể hàng loạt` hoặc khi nhập mặt hàng qua `Nhập từ Excel`.

| Trường | Mô tả |
| --- | --- |
| id | ID mặt hàng |
| name | Tên mặt hàng |
| sku | SKU |
| barcode | Mã vạch |
| photo_url | URL ảnh |
| cost | Giá vốn |
| price | Giá bán |
| attrs | Thuộc tính |

#### 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.

> **Caution**
>
> **Lưu ý**: Sự kiện này _không_ được kích hoạt với các chỉnh sửa hàng loạt thực hiện qua `Quản lý dữ liệu` > `Mặt hàng` hoặc qua chức năng `Nhập từ Excel`.

| Trường | Mô tả |
| --- | --- |
| id | ID mặt hàng |
| name | Tên mặt hàng |
| sku | SKU |
| barcode | Mã vạch |
| photo_url | URL ảnh |
| cost | Giá vốn |
| price | Giá bán |
| attrs | Thuộc tính |

#### Ví dụ payload – Mặt hàng được 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 tồn kho của nhóm.

> **Caution**
>
> **Lưu ý**: Sự kiện này _không_ được kích hoạt với các thao tác xóa hàng loạt thực hiện qua `Quản lý dữ liệu` > `Mặt hàng`.

| Trường | Mô tả |
| --- | --- |
| id | ID mặt hàng |

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

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