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.

Đă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.

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:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "id": 26122826
}