跳到內容
使用指南
English한국어DeutschEspañolFrançaisBahasa Indonesia日本語PortuguêsРусскийไทยTiếng Việt简体中文繁體中文

Webhook

Webhook 是一項功能，可讓您在 BoxHero 中發生特定事件時即時收到通知。

註冊

Section titled “註冊”

您可以在 BoxHero 團隊的 設定 > 整合和 API 中註冊 Webhook。

傳送與重試機制

Section titled “傳送與重試機制”

發生事件時，BoxHero 會向您註冊的 Webhook 端點傳送 HTTP POST 請求。請求內文包含描述該事件的 JSON Payload。

  • 若您的伺服器回應任何 2xx 狀態碼（例如 200、201、204），即視為傳送成功。
  • 任何 非 2xx 的回應 都會視為失敗，並將重新傳送。

Webhook Payload 結構

Section titled “Webhook Payload 結構”

所有 Webhook 事件都會以下列 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)
}

事件順序

Section titled “事件順序”

BoxHero 不保證事件傳送的順序。例如，同一品項的 item/new 事件可能會在 item/delete 事件之後才送達。

事件 Payload 中的 created_time 欄位代表事件實際發生的時間。請在您的 Webhook 處理程式中實作具冪等性且不受順序影響的邏輯，以可靠地處理事件。

事件主題

Section titled “事件主題”

txs/new

Section titled “txs/new”

發生庫存交易（入庫 / 出庫 / 調整 / 移動）時觸發。

欄位必填說明
id✓交易的唯一 ID
type✓交易類型
（in、out、adjust、move）
partner合作夥伴
partner.id合作夥伴的唯一 ID
partner.name合作夥伴名稱
partner.deleted合作夥伴是否已刪除
from_location來源位置
from_location.id來源位置的唯一 ID
from_location.name來源位置名稱
from_location.deleted來源位置是否已刪除
to_location✓目的地位置
to_location.id✓目的地位置的唯一 ID
to_location.name✓目的地位置名稱
to_location.deleted✓目的地位置是否已刪除
items✓交易中的明細項目
items.id✓品項的唯一 ID
items.name✓品項名稱
items.quantity✓因入庫 / 出庫 / 調整 / 移動而產生的庫存變動量
items.deleted✓品項是否已刪除
items.from_location_new_stock_level交易後來源位置的庫存量
items.to_location_new_stock_level✓交易後目的地位置的庫存量
transaction_time✓交易時間（例如入庫 / 出庫時間）
created_at✓交易的建立時間
created_by✓建立交易的成員
created_by.id✓成員的唯一 ID
created_by.name✓成員名稱
created_by.deleted✓成員是否已刪除
count_of_items✓品項數量
total_quantity✓庫存變動總量
url✓查看交易詳細資訊頁面的 URL 位址
memo與交易相關的備註

Webhook Payload 範例 – Stock In 事件

Section titled “Webhook Payload 範例 – 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"
}

Webhook Payload 範例 – Move Stock 事件

Section titled “Webhook Payload 範例 – 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

Section titled “txs/edit”

在現有的庫存交易（入庫 / 出庫 / 移動 / 調整）被編輯時傳送。

欄位必填說明
id✓交易的唯一 ID
type✓交易類型
（in、out、adjust、move）
partner合作夥伴
partner.id合作夥伴的唯一 ID
partner.name合作夥伴名稱
partner.deleted合作夥伴是否已刪除
from_location來源位置
from_location.id來源位置的唯一 ID
from_location.name來源位置名稱
from_location.deleted來源位置是否已刪除
to_location✓目的地位置
to_location.id✓目的地位置的唯一 ID
to_location.name✓目的地位置名稱
to_location.deleted✓目的地位置是否已刪除
items✓交易中的明細項目
items.id✓品項的唯一 ID
items.name✓品項名稱
items.quantity✓因交易（入庫 / 出庫 / 調整 / 移動）而產生的數量變動
items.deleted✓品項是否已刪除
items.from_location_new_stock_level交易後來源位置的庫存量
items.to_location_new_stock_level✓交易後目的地位置的庫存量
transaction_time✓交易時間（例如入庫 / 出庫時間）
created_at✓交易的建立時間
created_by✓建立交易的成員
created_by.id✓成員的唯一 ID
created_by.name✓成員名稱
created_by.deleted✓成員是否已刪除
count_of_items✓品項數量
total_quantity✓庫存變動總量
url✓查看交易詳細資訊頁面的 URL 位址
memo與交易相關的備註
revision✓交易目前的版本號碼，從 1 開始

Webhook Payload 範例 – 已編輯的 Stock In 交易

Section titled “Webhook Payload 範例 – 已編輯的 Stock In 交易”
{
  "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"
}

Webhook Payload 範例 – 已編輯的 Move Stock 交易

Section titled “Webhook Payload 範例 – 已編輯的 Move Stock 交易”
{
  "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

Section titled “txs/delete”

在庫存交易被刪除時傳送。

欄位說明
id交易的唯一 ID
revision交易目前的版本號碼，從 1 開始

Webhook Payload 範例 – 已刪除的交易

Section titled “Webhook Payload 範例 – 已刪除的交易”
{
  "id": 27036740,
  "revision": 2
}

item/new

Section titled “item/new”

在團隊庫存中新增品項時傳送。

欄位說明
id品項 ID
name品項名稱
skuSKU
barcode條碼
photo_url照片 URL
cost成本
price價格
attrs屬性

Payload 範例 – 品項已建立

Section titled “Payload 範例 – 品項已建立”
{
  "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

Section titled “item/edit”

在現有品項被編輯時傳送。

欄位說明
id品項 ID
name品項名稱
skuSKU
barcode條碼
photo_url照片 URL
cost成本
price價格
attrs屬性

Payload 範例 – 品項已更新

Section titled “Payload 範例 – 品項已更新”
{
  "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

Section titled “item/delete”

從團隊庫存中刪除品項時傳送。

欄位說明
id品項 ID

Payload 範例 – 品項已刪除

Section titled “Payload 範例 – 品項已刪除”
{
  "id": 26122826
}