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 & API trong nhóm 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 yêu cầu HTTP POST đến điểm cuối webhook đã đăng ký của bạn. Phần thân yêu cầu 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 nào khác 200, BoxHero xem đó là lỗi tạm thời và sẽ 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 yêu cầu:

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

Thứ tự sự kiện

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

Trườ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 bộ xử lý webhook của bạn để xử lý sự kiện một cách tin cậy.

Chủ đề sự kiện

Nếu bạn cần hỗ trợ cho các chủ đề sự kiện bổ sung, vui lòng liên hệ Hỗ trợ.

`txs/new`

Kích hoạt khi phát sinh 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 cho 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).

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

{
  "id": 16160911,
  "type": "in",
  "to_location": {
    "id": 52766,
    "name": "Kho 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": "Kho 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Kho 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.

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

{
  "id": 16160911,
  "type": "in",
  "to_location": {
    "id": 52766,
    "name": "Kho 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": "Kho 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Kho 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 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 nhóm.

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 thông qua Nhập Excel.

Bắt buộc

Trường

Mô tả

ID mặt hàng

tên

Tên mặt hàng

sku

SKU

mã vạch

Mã vạch

photo_url

URL ảnh

chi phí

Chi phí

giá

Giá

attrs

Thuộc tính

Ví dụ payload – Mặt hàng đã 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": "Danh mục",
      "type": "text",
      "value": "Foundation"
    },
    {
      "id": 459264,
      "name": "Ngày hết hạn",
      "type": "date",
      "value": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "Tồn kho an toàn",
      "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 chỉnh sửa hàng loạt được thực hiện thông qua Trung tâm dữ liệu > Mặt hàng hoặc thông qua Nhập Excel hàm.

Bắt buộc

Trường

Mô tả

ID mặt hàng

tên

Tên mặt hàng

sku

SKU

mã vạch

Mã vạch

photo_url

URL ảnh

chi phí

Chi phí

giá

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": "Danh mục",
      "type": "text",
      "value": "Foundation"
    },
    {
      "id": 459264,
      "name": "Ngày hết hạn",
      "type": "date",
      "value": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "Tồn kho an toàn",
      "type": "number",
      "value": 33
    }
  ]
}

`item/delete`

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

Lưu ý: Sự kiện này không được kích hoạt cho các thao tác xóa hàng loạt được thực hiện thông qua Trung tâm dữ liệu > Mặt hàng.

Trường

Mô tả

ID mặt hàng

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

{
  "id": 26122826
}

TrướcTài khoản Tiếp theoSlack

Cập nhật lần cuối 1 tháng trước

Đăng ký

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

Cấu trúc payload Webhook

Thứ tự sự kiện

Chủ đề sự kiện

txs/new

Ví dụ payload Webhook – Nhập kho Sự kiện

Ví dụ payload Webhook – Chuyển kho Sự kiện

txs/edit

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

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

txs/delete

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

item/new

Ví dụ payload – Mặt hàng đã tạo

item/edit

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

item/delete

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

`txs/new`

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

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

`txs/edit`

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

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

`txs/delete`

`item/new`

`item/edit`

`item/delete`