Webhook

Webhook là một 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ý một webhook tại Cài đặt > Tích hợp 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 bất kỳ mã trạng thái 2xx (ví dụ: 200, 201, 204), việc gửi được coi là thành công.
Bất kỳ phản hồi không thuộc 2xx được coi là thất bại và sẽ được thử lại.

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": "3f9a2b7c-6d4e-4a1f-9c8b-2e5d7a0f1b34", // 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 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.

Trường created_time trong payload sự kiện đại diện cho 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 đáng 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`

Đượ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 là 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).

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 / Chuyển kho / Điều chỉnh kho) được chỉnh sửa.

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

{
  "id": 16160911,
  "revision": 2,
  "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,
  "revision": 2,
  "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

bản sửa đổi

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.

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

Bắt buộc

Trường

Mô tả

ID mặt hàng

tên

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": "Danh mục",
      "type": "text",
      "value": "Kem nền"
    },
    {
      "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 là không được kích hoạt cho cá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 từ 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

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ậ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": "Kem nền"
    },
    {
      "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 tồn kho của nhóm.

Lưu ý: Sự kiện này là 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 2 ngày 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 được 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`