Webhook

Webhook là các 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.

---

Đăng ký

Bạn có thể đăng ký webhook tại Cài đặt > Tích hợp & API 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:

{
  "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

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

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

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

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)
đối tác		Đố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 có bị xóa hay không
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 có bị xóa hay không
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 có bị xóa hay không
items		Các dòng 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		Thay đổi tồn kho do nhập/xuất/điều chỉnh/chuyển
items.deleted		Mặt hàng có bị xóa hay không
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 điểm 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 có bị xóa hay không
count_of_items		Số lượng mặt hàng
total_quantity		Tổng số lượng thay đổi tồn kho
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 – Nhập kho Sự kiện

{
  "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

{
  "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 / Điều chỉnh tồn kho / Chuyển kho) đượ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)
đối tác		Đố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 có bị xóa hay không
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 có bị xóa hay không
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 có bị xóa hay không
items		Các dòng 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		Thay đổi số lượng do giao dịch (in/out/adjust/move)
items.deleted		Mặt hàng có bị xóa hay không
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 điểm 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 có bị xóa hay không
count_of_items		Số lượng mặt hàng
total_quantity		Tổng số lượng thay đổi tồn kho
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 – Đã chỉnh sửa Nhập kho Giao dịch

{
  "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

{
  "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

/{
  "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.

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

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

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

{
  "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.

Lưu ý: Sự kiện này không được kích hoạt fhoặc Trung tâm dữ liệu > Item hoặc qua Import Excel chức năng.

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

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

{
  "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.

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 Trung tâm dữ liệu > Item.

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

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

{
  "id": 26122826
}