Webhook

Webhook ialah ciri yang membolehkan anda menerima pemberitahuan masa nyata apabila peristiwa tertentu berlaku dalam BoxHero.

---

Pendaftaran

Anda boleh mendaftarkan webhook di Tetapan > Integrasi & API dalam pasukan BoxHero anda.

Gelagat Penghantaran & Cuba Semula

Apabila sesuatu peristiwa berlaku, BoxHero menghantar HTTP POST permintaan ke titik akhir webhook anda yang berdaftar. Badan permintaan mengandungi muatan JSON yang menerangkan peristiwa tersebut.

• Jika pelayan anda membalas dengan HTTP 200 OK, peristiwa itu dianggap berjaya dihantar.

• Jika pelayan anda membalas dengan sebarang kod status bukan 200, BoxHero menganggapnya sebagai kegagalan sementara dan akan mencuba semula penghantaran sehingga 3 kali.

Struktur Muatan Webhook

Semua peristiwa webhook dihantar dengan struktur JSON berikut dalam badan permintaan:

{
  "id": "1234", // ID unik peristiwa
  "topic": "txs/new", // Topik peristiwa
  "version": 1, // Versi skema muatan
  "payload": { // Data khusus peristiwa
    ...
  },
  "created_time": "2025-08-06T09:20:48.623Z" // Cap masa berlakunya peristiwa (ISO 8601)
}

---

Susunan Peristiwa

BoxHero tidak menjamin susunan penghantaran peristiwa. Contohnya, satu peristiwa item/new mungkin tiba selepas peristiwa item/delete untuk item yang sama.

Ciri created_time medan dalam muatan peristiwa mewakili masa peristiwa sebenar. Laksanakan logik idempotent dan tahan susunan dalam pengendali webhook anda untuk mengendalikan peristiwa dengan boleh dipercayai.

Topik Peristiwa

Jika anda memerlukan sokongan untuk topik peristiwa tambahan, sila hubungi Sokongan.

txs/new

Dicetuskan apabila transaksi inventori berlaku (Stok Masuk / Stok Keluar / Laras Stok / Pindah Stok).

Nota: Peristiwa ini tidak dicetuskan untuk pelarasan yang dibuat melalui pengeditan pukal atau import (cth., apabila menambah atau mengemas kini item melalui Excel).

Medan	Diperlukan	Perihalan
id		ID unik transaksi
type		Jenis transaksi (in, out, adjust, move)
rakan kongsi		Rakan kongsi
partner.id		ID unik rakan kongsi
partner.name		Nama rakan kongsi
partner.deleted		Sama ada rakan kongsi dipadamkan
from_location		Lokasi sumber
from_location.id		ID unik lokasi sumber
from_location.name		Nama lokasi sumber
from_location.deleted		Sama ada lokasi sumber dipadamkan
to_location		Lokasi destinasi
to_location.id		ID unik lokasi destinasi
to_location.name		Nama lokasi destinasi
to_location.deleted		Sama ada lokasi destinasi dipadamkan
items		Item baris dalam transaksi
items.id		ID unik item
items.name		Nama item
items.quantity		Perubahan inventori akibat stok masuk/keluar/laras/pindah
items.deleted		Sama ada item dipadamkan
items.from_location_new_stock_level		Tahap stok di lokasi sumber selepas transaksi
items.to_location_new_stock_level		Tahap stok di lokasi destinasi selepas transaksi
transaction_time		Masa transaksi (cth. masa stok masuk/keluar)
created_at		Masa apabila transaksi dicipta
created_by		Ahli yang mencipta transaksi
created_by.id		ID unik ahli
created_by.name		Nama ahli
created_by.deleted		Sama ada ahli dipadamkan
count_of_items		Bilangan item
total_quantity		Jumlah perubahan inventori
url		Alamat URL untuk melihat halaman butiran transaksi
memo		Nota berkaitan transaksi

Contoh Muatan Webhook – Stok Masuk Peristiwa

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

Contoh Muatan Webhook – Pindahkan Stok Peristiwa

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

Dihantar apabila transaksi inventori yang sedia ada (Stok Masuk / Stok Keluar / Laras Stok / Pindah Stok) disunting.

Medan	Diperlukan	Perihalan
id		ID unik transaksi
type		Jenis transaksi (in, out, adjust, move)
rakan kongsi		Rakan kongsi
partner.id		ID unik rakan kongsi
partner.name		Nama rakan kongsi
partner.deleted		Sama ada rakan kongsi dipadamkan
from_location		Lokasi sumber
from_location.id		ID unik lokasi sumber
from_location.name		Nama lokasi sumber
from_location.deleted		Sama ada lokasi sumber dipadamkan
to_location		Lokasi destinasi
to_location.id		ID unik lokasi destinasi
to_location.name		Nama lokasi destinasi
to_location.deleted		Sama ada lokasi destinasi dipadamkan
items		Item baris dalam transaksi
items.id		ID unik item
items.name		Nama item
items.quantity		Perubahan kuantiti akibat transaksi (in/out/adjust/move)
items.deleted		Sama ada item dipadamkan
items.from_location_new_stock_level		Tahap stok di lokasi sumber selepas transaksi
items.to_location_new_stock_level		Tahap stok di lokasi destinasi selepas transaksi
transaction_time		Masa transaksi (cth. masa stok masuk/keluar)
created_at		Masa apabila transaksi dicipta
created_by		Ahli yang mencipta transaksi
created_by.id		ID unik ahli
created_by.name		Nama ahli
created_by.deleted		Sama ada ahli dipadamkan
count_of_items		Bilangan item
total_quantity		Jumlah perubahan inventori
url		Alamat URL untuk melihat halaman butiran transaksi
memo		Nota berkaitan transaksi
revision		Nombor versi semasa transaksi, bermula dari 1

Contoh Muatan Webhook – Disunting Stok Masuk Transaksi

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

Contoh Muatan Webhook – Disunting Pindahkan Stok Transaksi

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

Dihantar apabila transaksi inventori dipadamkan.

Medan	Perihalan
id	ID unik transaksi
revision	Nombor versi semasa transaksi, bermula dari 1

Contoh Muatan Webhook – Transaksi Dipadamkan

/{
  "id": 27036740,
  "revision": 2
}

item/new

Dihantar apabila item baharu ditambah ke inventori pasukan.

Nota: Peristiwa ini tidak dicetuskan apabila menggunakan Tambah Variasi Item ciri atau mengimport item melalui Import Excel.

Medan	Perihalan
id	ID Item
nama	Nama Item
sku	SKU
kod bar	Kod Bar
photo_url	URL Foto
kos	Kos
harga	Harga
attrs	Atribut

Contoh Muatan – Item Dicipta

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

Dihantar apabila item sedia ada disunting.

Nota: Peristiwa ini tidak dicetuskan for pengeditan pukal yang dibuat melalui Pusat Data > Item atau melalui Import Excel fungsi.

Medan	Perihalan
id	ID Item
nama	Nama Item
sku	SKU
kod bar	Kod Bar
photo_url	URL Foto
kos	Kos
harga	Harga
attrs	Atribut

Contoh Muatan – Item Dikemas Kini

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

Dihantar apabila item dipadamkan daripada inventori pasukan.

Nota: Peristiwa ini tidak dicetuskan untuk pemadaman pukal yang dibuat melalui Pusat Data > Item.

Medan	Perihalan
id	ID Item

Contoh Muatan – Item Dipadamkan

{
  "id": 26122826
}