Ringkasan

Webhook adalah fitur yang memungkinkan Anda menerima notifikasi secara real-time saat peristiwa tertentu terjadi di BoxHero.

Pendaftaran

Anda dapat mendaftarkan webhook di Pengaturan > Integrasi pada tim BoxHero Anda.

Pengiriman & Percobaan Ulang

Saat suatu peristiwa terjadi, BoxHero mengirimkan permintaan HTTP POST ke endpoint webhook yang telah Anda daftarkan. Body permintaan berisi payload JSON yang menjelaskan peristiwa tersebut.

Jika server Anda merespons dengan kode status 2xx apa pun (misalnya 200, 201, 204), pengiriman dianggap berhasil.
Respons 5xx atau 429, kesalahan jaringan, atau waktu habis (8 detik) dianggap kegagalan sementara dan akan dicoba ulang.
Respons 4xx lainnya dianggap kegagalan permanen dan tidak akan dicoba ulang.

Struktur Payload Webhook

Semua peristiwa webhook dikirim dengan struktur JSON berikut di dalam body permintaan:

{
  "id": "3f9a2b7c-6d4e-4a1f-9c8b-2e5d7a0f1b34", // Event's unique ID
  "topic": "txs/new", // Event topic
  "version": 2, // Payload schema version (varies by topic: 2 for txs/new, 1 for the others)
  "team_id": 149058, // Team's unique ID
  "payload": { // Event-specific data
    ...
  },
  "created_time": "2025-08-06T09:20:48.623Z" // Timestamp of event occurrence (ISO 8601)
}

Urutan Peristiwa

BoxHero tidak menjamin urutan pengiriman peristiwa. Misalnya, peristiwa item/new dapat tiba setelah peristiwa item/delete untuk barang yang sama.

Field created_time dalam payload peristiwa menunjukkan waktu peristiwa yang sebenarnya. Terapkan logika yang idempoten dan toleran terhadap urutan pada handler webhook Anda agar peristiwa dapat ditangani dengan andal.

Peristiwa transaksi (txs/new, txs/edit, txs/delete) juga menyertakan revision, sehingga Anda dapat mengetahui versi transaksi mana yang dijelaskan oleh suatu peristiwa.

Topik Peristiwa

txs/new

Dipicu saat terjadi transaksi stok (Stok Masuk / Stok Keluar / Penyesuaian Stok / Transfer Stok).

Field	Wajib	Deskripsi
id	✓	ID unik transaksi
type	✓	Jenis transaksi (in, out, adjust, move)
partner		Partner
partner.id		ID unik partner
partner.name		Nama partner
partner.deleted		Apakah partner telah dihapus
from_location		Lokasi asal
from_location.id		ID unik lokasi asal
from_location.name		Nama lokasi asal
from_location.deleted		Apakah lokasi asal telah dihapus
to_location	✓	Lokasi tujuan
to_location.id	✓	ID unik lokasi tujuan
to_location.name	✓	Nama lokasi tujuan
to_location.deleted	✓	Apakah lokasi tujuan telah dihapus
items	✓	Daftar barang dalam transaksi
items.id	✓	ID unik barang
items.name	✓	Nama barang
items.quantity	✓	Perubahan stok akibat stok masuk/keluar/audit/transfer
items.deleted	✓	Apakah barang telah dihapus
items.from_location_new_stock_level		Tingkat stok di lokasi asal setelah transaksi
items.to_location_new_stock_level	✓	Tingkat stok di lokasi tujuan setelah transaksi
transaction_time	✓	Waktu transaksi (misalnya waktu stok masuk/keluar)
created_at	✓	Waktu saat transaksi dibuat
created_by	✓	Anggota yang membuat transaksi
created_by.id	✓	ID unik anggota
created_by.name	✓	Nama anggota
created_by.deleted	✓	Apakah anggota telah dihapus
count_of_items	✓	Jumlah barang
total_quantity	✓	Total perubahan stok
url	✓	Alamat URL untuk melihat halaman detail transaksi
memo		Catatan terkait transaksi
revision	✓	Nomor versi transaksi saat ini, dimulai dari 1

Contoh Payload Webhook – Peristiwa Stock In

{
  "id": 16160911,
  "revision": 1,
  "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/2#/ltx/16160911"
}

Contoh Payload Webhook – Peristiwa Move Stock

{
  "id": 3692714,
  "revision": 1,
  "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

Dikirim saat transaksi stok yang sudah ada (Stok Masuk / Stok Keluar / Transfer Stok / Penyesuaian Stok) diedit.

Field	Wajib	Deskripsi
id	✓	ID unik transaksi
type	✓	Jenis transaksi (in, out, adjust, move)
partner		Partner
partner.id		ID unik partner
partner.name		Nama partner
partner.deleted		Apakah partner telah dihapus
from_location		Lokasi asal
from_location.id		ID unik lokasi asal
from_location.name		Nama lokasi asal
from_location.deleted		Apakah lokasi asal telah dihapus
to_location	✓	Lokasi tujuan
to_location.id	✓	ID unik lokasi tujuan
to_location.name	✓	Nama lokasi tujuan
to_location.deleted	✓	Apakah lokasi tujuan telah dihapus
items	✓	Daftar barang dalam transaksi
items.id	✓	ID unik barang
items.name	✓	Nama barang
items.quantity	✓	Perubahan kuantitas akibat transaksi (in/out/adjust/move)
items.deleted	✓	Apakah barang telah dihapus
items.from_location_new_stock_level		Tingkat stok di lokasi asal setelah transaksi
items.to_location_new_stock_level	✓	Tingkat stok di lokasi tujuan setelah transaksi
transaction_time	✓	Waktu transaksi (misalnya waktu stok masuk/keluar)
created_at	✓	Waktu saat transaksi dibuat
created_by	✓	Anggota yang membuat transaksi
created_by.id	✓	ID unik anggota
created_by.name	✓	Nama anggota
created_by.deleted	✓	Apakah anggota telah dihapus
count_of_items	✓	Jumlah barang
total_quantity	✓	Total perubahan stok
url	✓	Alamat URL untuk melihat halaman detail transaksi
memo		Catatan terkait transaksi
revision	✓	Nomor versi transaksi saat ini, dimulai dari 1

Contoh Payload Webhook – Transaksi Stock In yang Diedit

{
  "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/2#/ltx/16160911"
}

Contoh Payload Webhook – Transaksi Move Stock yang Diedit

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

Dikirim saat transaksi stok dihapus.

Field	Deskripsi
id	ID unik transaksi
revision	Nomor versi transaksi saat ini, dimulai dari 1

Contoh Payload Webhook – Transaksi yang Dihapus

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

item/new

Dikirim saat barang baru ditambahkan ke stok tim.

Field	Deskripsi
id	ID barang
name	Nama barang
sku	SKU
barcode	Barcode
photo_url	URL foto
cost	Harga Beli
price	Harga Jual
attrs	Atribut

Contoh Payload – Barang Dibuat

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

Dikirim saat barang yang sudah ada diedit.

Field	Deskripsi
id	ID barang
name	Nama barang
sku	SKU
barcode	Barcode
photo_url	URL foto
cost	Harga Beli
price	Harga Jual
attrs	Atribut

Contoh Payload – Barang Diperbarui

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

Dikirim saat barang dihapus dari stok tim.

Field	Deskripsi
id	ID barang

Contoh Payload – Barang Dihapus

{
  "id": 26122826
}