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.

Tingkah laku penghantaran & percubaan semula

Apabila peristiwa berlaku, BoxHero menghantar HTTP POST permintaan ke endpoint webhook yang anda daftarkan. Badan permintaan mengandungi beban JSON yang menerangkan peristiwa itu.

• 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 mencuba semula penghantaran sehingga 3 kali.

Struktur Beban 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 beban
  "payload": { // Data khusus peristiwa
    ...
  },
  "created_time": "2025-08-06T09:20:48.623Z" // Cap masa berlakunya peristiwa (ISO 8601)
}

---

Urutan Peristiwa

BoxHero tidak menjamin susunan penghantaran peristiwa. Sebagai contoh, satu item/new peristiwa boleh tiba selepas satu item/delete peristiwa bagi item yang sama.

Medan created_time dalam beban peristiwa mewakili masa sebenar peristiwa. Laksanakan logik idempoten dan tahan terhadap 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 / Laraskan Stok / Pindah Stok).

Catatan: Peristiwa ini tidak dicetuskan untuk pelarasan yang dibuat melalui suntingan kelompok atau import (cth., apabila menambah atau mengemas kini item melalui Excel).

DiperlukanDiperlukan

Medan	Diperlukan	Penerangan
id		ID unik transaksi
type		Jenis transaksi\n(in, out, adjust, move)
partner		Rakan kongsi
partner.id		ID unik rakan kongsi
partner.name		Nama rakan kongsi
partner.deleted		Sama ada rakan kongsi dipadam
from_location		Lokasi sumber
from_location.id		ID unik lokasi sumber
from_location.name		Nama lokasi sumber
from_location.deleted		Sama ada lokasi sumber dipadam
to_location		Lokasi destinasi
to_location.id		ID unik lokasi destinasi
to_location.name		Nama lokasi destinasi
to_location.deleted		Sama ada lokasi destinasi dipadam
items		Item baris dalam transaksi
items.id		ID unik item
items.name		Nama item
items.quantity		Perubahan inventori akibat stok masuk/keluar/pelarasan/pindahan
items.deleted		Sama ada item dipadam
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 dipadam
count_of_items		Bilangan item
total_quantity		Jumlah keseluruhan perubahan inventori
url		Alamat URL untuk melihat halaman butiran transaksi
memo		Nota berkaitan transaksi

Contoh Beban Webhook – Stok Masuk Peristiwa

{
  "id": 16160911,
  "type": "in",
  "to_location": {
    "id": 52766,
    "name": "Gudang 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 Beban Webhook – Pindah Stok Peristiwa

{
  "id": 3692714,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "Gudang 2,","t_ffdda55f":""id": 14873303,
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Gudang 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 sedia ada (Stok Masuk / Stok Keluar / Laraskan Stok / Pindah Stok) is diedit.

DiperlukanDiperlukan

Medan	Diperlukan	Penerangan
id		ID unik transaksi
type		Jenis transaksi\n(in, out, adjust, move)
partner		Rakan kongsi
partner.id		ID unik rakan kongsi
partner.name		Nama rakan kongsi
partner.deleted		Sama ada rakan kongsi dipadam
from_location		Lokasi sumber
from_location.id		ID unik lokasi sumber
from_location.name		Nama lokasi sumber
from_location.deleted		Sama ada lokasi sumber dipadam
to_location		Lokasi destinasi
to_location.id		ID unik lokasi destinasi
to_location.name		Nama lokasi destinasi
to_location.deleted		Sama ada lokasi destinasi dipadam
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 dipadam
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 dipadam
count_of_items		Bilangan item
total_quantity		Jumlah keseluruhan perubahan inventori
url		Alamat URL untuk melihat halaman butiran transaksi
memo		Nota berkaitan transaksi
revisi		Nombor versi semasa transaksi, bermula dari 1

Contoh Beban Webhook – Diedit Stok Masuk Transaksi

{
  "id": 16160911,
  "type": "in",
  "to_location": {
    "id": 52766,
    "name": "Gudang 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 Beban Webhook – Diedit Pindah Stok Transaksi

{
  "id": 3692714,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "Gudang 2,","t_ffdda55f":""id": 14873303,
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Gudang 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 dipadam.

Medan	Penerangan
id	ID unik transaksi
revisi	Nombor versi semasa transaksi, bermula dari 1

Contoh Beban Webhook – Transaksi Dipadam

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

item/new

Dihantar apabila item baharu ditambah ke inventori pasukan.

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

Diperlukan

Medan	Penerangan
id	ID Item
nama	Nama Item
sku	SKU
barcode	Kod Bar
photo_url	URL Foto
cost	Kos
price	Harga
attrs	Atribut

Contoh Beban – 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": "Kategori",
      "type": "text",
      "value": "Bedak asas"
    },
    {
      "id": 459264,
      "name": "Tarikh luput",
      "type": "date",
      "value": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "Stok keselamatan",
      "type": "number",
      "value": 33
    }
  ]
}

item/edit

Dihantar apabila item sedia ada diedit.

Catatan: Peristiwa ini tidak dicetuskan fatau suntingan kelompok yang dibuat melalui Pusat Data > Item atau melalui Import Excel fungsi.

Diperlukan

Medan	Penerangan
id	ID Item
nama	Nama Item
sku	SKU
barcode	Kod Bar
photo_url	URL Foto
cost	Kos
price	Harga
attrs	Atribut

Contoh Beban – 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": "Kategori",
      "type": "text",
      "value": "Bedak asas"
    },
    {
      "id": 459264,
      "name": "Tarikh luput",
      "type": "date",
      "value": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "Stok keselamatan",
      "type": "number",
      "value": 33
    }
  ]
}

item/delete

Dihantar apabila item dipadam daripada inventori pasukan.

Catatan: Peristiwa ini tidak dicetuskan untuk pemadaman kelompok yang dibuat melalui Pusat Data > Item.

Medan	Penerangan
id	ID Item

Contoh Beban – Item Dipadam

{
  "id": 26122826
}