> For the complete documentation index, see [llms.txt](https://www.boxhero.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.boxhero.io/docs/documentation/ms/integrasi/webhook.md).

# Webhook

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

<figure><img src="https://4224534249-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlRf1QqJGoevCQqGbfI80%2Fuploads%2FY1xAFhph1Gpp4FxnSZ7I%2F05_API.jpg?alt=media&amp;token=500a0d78-d0b9-4c05-a3ee-02f1d7d91039" alt=""><figcaption></figcaption></figure>

***

## Pendaftaran

Anda boleh mendaftar webhook di <mark style="color:$primary;">`Tetapan`</mark> > <mark style="color:$primary;">`Integrasi`</mark> dalam pasukan BoxHero anda.

<figure><img src="https://4224534249-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlRf1QqJGoevCQqGbfI80%2Fuploads%2Fgit-blob-094f1326e4f5b66d3f4de825a63e55cbf0f4ac01%2Fboxhero-add-webhook.png?alt=media" alt=""><figcaption></figcaption></figure>

## Gelagat Penghantaran & Cuba Semula

Apabila acara berlaku, BoxHero menghantar HTTP `POST` permintaan ke titik akhir webhook yang anda daftarkan. Badan permintaan mengandungi muatan JSON yang menerangkan acara tersebut.

* Jika pelayan anda membalas dengan sebarang **kod status 2xx** (cth., 200, 201, 204), penghantaran dianggap berjaya.
* Sebarang **respons bukan 2xx** dianggap gagal dan akan dicuba semula.

## Struktur Muatan Webhook

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

```json
{
  "id": "3f9a2b7c-6d4e-4a1f-9c8b-2e5d7a0f1b34", // ID unik acara
  "topic": "txs/new", // Topik acara
  "version": 1, // Versi skema muatan
  "payload": { // Data khusus acara
    ...
  },
  "created_time": "2025-08-06T09:20:48.623Z" // Cap masa berlakunya acara (ISO 8601)
}
```

***

## Susunan Acara

BoxHero **tidak** menjamin susunan penghantaran acara. Contohnya, sebuah `item/new` acara mungkin tiba selepas sebuah `item/delete` acara bagi item yang sama.

Pihak `created_time` medan dalam muatan acara mewakili masa acara sebenar. Laksanakan logik idempoten dan toleran terhadap susunan dalam pengendali webhook anda untuk mengendalikan acara dengan boleh dipercayai.

## Topik Acara

{% hint style="info" %}
Jika anda memerlukan sokongan untuk topik acara tambahan, sila hubungi [Sokongan](/docs/documentation/ms/sumber/contact.md).
{% endhint %}

### `txs/new`

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

{% hint style="warning" %}
**Nota:** Acara ini *tidak* dicetuskan untuk pelarasan yang dibuat melalui suntingan pukal atau import (cth., apabila menambah atau mengemas kini item melalui Excel).
{% endhint %}

<table><thead><tr><th width="207">Medan</th><th width="100" data-type="checkbox">Diperlukan</th><th>Huraian</th><th data-hidden data-type="checkbox">Wajib</th><th data-hidden>Penerangan</th><th data-hidden>Mod pasukan</th></tr></thead><tbody><tr><td>id</td><td>true</td><td>ID unik transaksi</td><td>true</td><td>ID unik transaksi</td><td>Semua</td></tr><tr><td>type</td><td>true</td><td>Jenis transaksi<br>(in, out, adjust, move)</td><td>true</td><td><p>Jenis transaksi.</p><ul><li>Masuk stok : in</li><li>Keluar stok : out</li><li>Pelarasan : adjust</li><li>Pindah : move</li></ul></td><td>Semua</td></tr><tr><td>rakan kongsi</td><td>false</td><td>Rakan kongsi</td><td>false</td><td></td><td></td></tr><tr><td>partner.id</td><td>false</td><td>ID unik rakan kongsi</td><td>false</td><td></td><td></td></tr><tr><td>partner.name</td><td>false</td><td>Nama rakan kongsi</td><td>false</td><td></td><td></td></tr><tr><td>partner.deleted</td><td>false</td><td>Sama ada rakan kongsi dipadam</td><td>false</td><td></td><td></td></tr><tr><td>from_location</td><td>false</td><td>Lokasi sumber</td><td>false</td><td></td><td></td></tr><tr><td>from_location.id</td><td>false</td><td>ID unik lokasi sumber</td><td>false</td><td></td><td></td></tr><tr><td>from_location.name</td><td>false</td><td>Nama lokasi sumber</td><td>false</td><td></td><td></td></tr><tr><td>from_location.deleted</td><td>false</td><td>Sama ada lokasi sumber dipadam</td><td>false</td><td></td><td></td></tr><tr><td>to_location</td><td>true</td><td>Lokasi destinasi</td><td>false</td><td></td><td></td></tr><tr><td>to_location.id</td><td>true</td><td>ID unik lokasi destinasi</td><td>false</td><td></td><td></td></tr><tr><td>to_location.name</td><td>true</td><td>Nama lokasi destinasi</td><td>false</td><td></td><td></td></tr><tr><td>to_location.deleted</td><td>true</td><td>Sama ada lokasi destinasi dipadam</td><td>false</td><td></td><td></td></tr><tr><td>item</td><td>true</td><td>Baris item dalam transaksi</td><td>true</td><td>Baris item mengikut produk yang membentuk transaksi</td><td>Semua mod</td></tr><tr><td>items.id</td><td>true</td><td>ID unik item</td><td>true</td><td>ID unik produk</td><td>Semua mod</td></tr><tr><td>items.name</td><td>true</td><td>Nama item</td><td>true</td><td>Nama produk</td><td>Semua mod</td></tr><tr><td>items.quantity</td><td>true</td><td>Perubahan inventori akibat stok masuk/keluar/pelarasan/pindah</td><td>true</td><td>Kuantiti masuk/keluar/pelarasan/pindah bagi produk tersebut</td><td>Semua mod</td></tr><tr><td>items.deleted</td><td>true</td><td>Sama ada item dipadam</td><td>true</td><td>Sama ada produk dipadam</td><td></td></tr><tr><td>items.from_location_new_stock_level</td><td>false</td><td>Tahap stok di lokasi sumber selepas transaksi</td><td>false</td><td></td><td></td></tr><tr><td>items.to_location_new_stock_level</td><td>true</td><td>Tahap stok di lokasi destinasi selepas transaksi</td><td>false</td><td></td><td></td></tr><tr><td>transaction_time</td><td>true</td><td>Masa transaksi (cth. masa stok masuk/keluar)</td><td>false</td><td></td><td></td></tr><tr><td>created_at</td><td>true</td><td>Masa apabila transaksi dicipta</td><td>false</td><td></td><td></td></tr><tr><td>created_by</td><td>true</td><td>Ahli yang mencipta transaksi</td><td>false</td><td></td><td></td></tr><tr><td>created_by.id</td><td>true</td><td>ID unik ahli</td><td>false</td><td></td><td></td></tr><tr><td>created_by.name</td><td>true</td><td>Nama ahli</td><td>false</td><td></td><td></td></tr><tr><td>created_by.deleted</td><td>true</td><td>Sama ada ahli dipadam</td><td>false</td><td></td><td></td></tr><tr><td>count_of_items</td><td>true</td><td>Bilangan item</td><td>false</td><td></td><td></td></tr><tr><td>total_quantity</td><td>true</td><td>Jumlah keseluruhan perubahan inventori</td><td>false</td><td></td><td></td></tr><tr><td>url</td><td>true</td><td>Alamat URL untuk melihat halaman butiran transaksi</td><td>false</td><td></td><td></td></tr><tr><td>memo</td><td>false</td><td>Nota berkaitan transaksi</td><td>false</td><td></td><td></td></tr></tbody></table>

#### Contoh Muatan Webhook – `Stok Masuk` Acara

```json
{
  "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` Acara

<pre class="language-json"><code class="lang-json">{
  "id": 3692714,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "Warehouse 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Warehouse 3",
<strong>    "deleted": false
</strong>  },
  "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"
}
</code></pre>

### `txs/edit`

Dihantar apabila transaksi inventori sedia ada (Stok Masuk / Stok Keluar / Pindah Stok / Laraskan Stok) telah **disunting**.

<table><thead><tr><th>Medan</th><th width="100" data-type="checkbox">Diperlukan</th><th>Huraian</th><th data-hidden data-type="checkbox">Wajib</th><th data-hidden>Penerangan</th><th data-hidden>Mod pasukan</th></tr></thead><tbody><tr><td>id</td><td>true</td><td>ID unik transaksi</td><td>true</td><td>ID unik transaksi</td><td>Semua</td></tr><tr><td>type</td><td>true</td><td>Jenis transaksi<br>(in, out, adjust, move)</td><td>true</td><td><p>Jenis transaksi.</p><ul><li>Masuk stok : in</li><li>Keluar stok : out</li><li>Pelarasan : adjust</li><li>Pindah : move</li></ul></td><td>Semua</td></tr><tr><td>rakan kongsi</td><td>false</td><td>Rakan kongsi</td><td>false</td><td></td><td></td></tr><tr><td>partner.id</td><td>false</td><td>ID unik rakan kongsi</td><td>false</td><td></td><td></td></tr><tr><td>partner.name</td><td>false</td><td>Nama rakan kongsi</td><td>false</td><td></td><td></td></tr><tr><td>partner.deleted</td><td>false</td><td>Sama ada rakan kongsi dipadam</td><td>false</td><td></td><td></td></tr><tr><td>from_location</td><td>false</td><td>Lokasi sumber</td><td>false</td><td></td><td></td></tr><tr><td>from_location.id</td><td>false</td><td>ID unik lokasi sumber</td><td>false</td><td></td><td></td></tr><tr><td>from_location.name</td><td>false</td><td>Nama lokasi sumber</td><td>false</td><td></td><td></td></tr><tr><td>from_location.deleted</td><td>false</td><td>Sama ada lokasi sumber dipadam</td><td>false</td><td></td><td></td></tr><tr><td>to_location</td><td>true</td><td>Lokasi destinasi</td><td>false</td><td></td><td></td></tr><tr><td>to_location.id</td><td>true</td><td>ID unik lokasi destinasi</td><td>false</td><td></td><td></td></tr><tr><td>to_location.name</td><td>true</td><td>Nama lokasi destinasi</td><td>false</td><td></td><td></td></tr><tr><td>to_location.deleted</td><td>true</td><td>Sama ada lokasi destinasi dipadam</td><td>false</td><td></td><td></td></tr><tr><td>item</td><td>true</td><td>Baris item dalam transaksi</td><td>true</td><td>Baris item mengikut produk yang membentuk transaksi</td><td>Semua mod</td></tr><tr><td>items.id</td><td>true</td><td>ID unik item</td><td>true</td><td>ID unik produk</td><td>Semua mod</td></tr><tr><td>items.name</td><td>true</td><td>Nama item</td><td>true</td><td>Nama produk</td><td>Semua mod</td></tr><tr><td>items.quantity</td><td>true</td><td>Perubahan kuantiti akibat transaksi (in/out/adjust/move)</td><td>true</td><td>Kuantiti masuk/keluar/pelarasan/pindah bagi produk tersebut</td><td>Semua mod</td></tr><tr><td>items.deleted</td><td>true</td><td>Sama ada item dipadam</td><td>true</td><td>Sama ada produk dipadam</td><td></td></tr><tr><td>items.from_location_new_stock_level</td><td>false</td><td>Tahap stok di lokasi sumber selepas transaksi</td><td>false</td><td></td><td></td></tr><tr><td>items.to_location_new_stock_level</td><td>true</td><td>Tahap stok di lokasi destinasi selepas transaksi</td><td>false</td><td></td><td></td></tr><tr><td>transaction_time</td><td>true</td><td>Masa transaksi (cth. masa stok masuk/keluar)</td><td>false</td><td></td><td></td></tr><tr><td>created_at</td><td>true</td><td>Masa apabila transaksi dicipta</td><td>false</td><td></td><td></td></tr><tr><td>created_by</td><td>true</td><td>Ahli yang mencipta transaksi</td><td>false</td><td></td><td></td></tr><tr><td>created_by.id</td><td>true</td><td>ID unik ahli</td><td>false</td><td></td><td></td></tr><tr><td>created_by.name</td><td>true</td><td>Nama ahli</td><td>false</td><td></td><td></td></tr><tr><td>created_by.deleted</td><td>true</td><td>Sama ada ahli dipadam</td><td>false</td><td></td><td></td></tr><tr><td>count_of_items</td><td>true</td><td>Bilangan item</td><td>false</td><td></td><td></td></tr><tr><td>total_quantity</td><td>true</td><td>Jumlah keseluruhan perubahan inventori</td><td>false</td><td></td><td></td></tr><tr><td>url</td><td>true</td><td>Alamat URL untuk melihat halaman butiran transaksi</td><td>false</td><td></td><td></td></tr><tr><td>memo</td><td>false</td><td>Nota berkaitan transaksi</td><td>false</td><td></td><td></td></tr><tr><td>revisi</td><td>true</td><td>Nombor versi semasa transaksi, bermula dari 1</td><td>false</td><td></td><td></td></tr></tbody></table>

#### Contoh Muatan Webhook – Disunting `Stok Masuk` Transaksi

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

```

#### Contoh Muatan Webhook – Disunting `Pindahkan Stok` Transaksi

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

Dihantar apabila transaksi inventori **dipadam**.

| Medan  | Huraian                                       |
| ------ | --------------------------------------------- |
| id     | ID unik transaksi                             |
| revisi | Nombor versi semasa transaksi, bermula dari 1 |

#### Contoh Muatan Webhook – Transaksi Dipadam

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

### `item/new`

Dihantar apabila item baharu ditambah ke inventori pasukan.

{% hint style="warning" %}
**Nota**: Acara ini *tidak* dicetuskan apabila menggunakan <mark style="color:$primary;">`Tambah Varian Item`</mark> ciri atau mengimport item melalui <mark style="color:$primary;">`Import daripada Excel`</mark>.
{% endhint %}

<table><thead><tr><th width="318">Medan</th><th>Huraian</th><th data-hidden data-type="checkbox">Wajib</th><th data-hidden>Penerangan</th><th data-hidden>Mod pasukan</th></tr></thead><tbody><tr><td>id</td><td>ID Item</td><td>true</td><td>ID unik transaksi</td><td>Semua</td></tr><tr><td>nama</td><td>Nama Item</td><td>true</td><td><p>Jenis transaksi.</p><ul><li>Masuk stok : in</li><li>Keluar stok : out</li><li>Pelarasan : adjust</li><li>Pindah : move</li></ul></td><td>Semua</td></tr><tr><td>sku</td><td>SKU</td><td>false</td><td></td><td></td></tr><tr><td>kod bar</td><td>Kod bar</td><td>false</td><td></td><td></td></tr><tr><td>photo_url</td><td>URL Foto</td><td>false</td><td></td><td></td></tr><tr><td>kos</td><td>Kos</td><td>false</td><td></td><td></td></tr><tr><td>harga</td><td>Harga</td><td>false</td><td></td><td></td></tr><tr><td>atribut</td><td>Atribut</td><td>false</td><td></td><td></td></tr></tbody></table>

#### **Contoh Muatan – Item Dicipta**

```json
{
  "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.

{% hint style="warning" %}
**Nota**: Acara ini *tidak* dicetuskan untuk suntingan pukal yang dibuat melalui <mark style="color:$primary;">`Pusat Data`</mark> > <mark style="color:$primary;">`Item`</mark> atau melalui <mark style="color:$primary;">`Import daripada Excel`</mark> fungsi.
{% endhint %}

<table><thead><tr><th width="318">Medan</th><th>Huraian</th><th data-hidden data-type="checkbox">Wajib</th><th data-hidden>Penerangan</th><th data-hidden>Mod pasukan</th></tr></thead><tbody><tr><td>id</td><td>ID Item</td><td>true</td><td>ID unik transaksi</td><td>Semua</td></tr><tr><td>nama</td><td>Nama Item</td><td>true</td><td><p>Jenis transaksi.</p><ul><li>Masuk stok : in</li><li>Keluar stok : out</li><li>Pelarasan : adjust</li><li>Pindah : move</li></ul></td><td>Semua</td></tr><tr><td>sku</td><td>SKU</td><td>false</td><td></td><td></td></tr><tr><td>kod bar</td><td>Kod bar</td><td>false</td><td></td><td></td></tr><tr><td>photo_url</td><td>URL Foto</td><td>false</td><td></td><td></td></tr><tr><td>kos</td><td>Kos</td><td>false</td><td></td><td></td></tr><tr><td>harga</td><td>Harga</td><td>false</td><td></td><td></td></tr><tr><td>atribut</td><td>Atribut</td><td>false</td><td></td><td></td></tr></tbody></table>

#### **Contoh Muatan – Item Dikemas kini**

```json
{
  "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 dipadam daripada inventori pasukan.

{% hint style="warning" %}
**Nota**: Acara ini *tidak* dicetuskan untuk pemadaman pukal yang dibuat melalui <mark style="color:$primary;">`Pusat Data`</mark> > <mark style="color:$primary;">`Item`</mark>.
{% endhint %}

<table><thead><tr><th width="318">Medan</th><th>Huraian</th><th data-hidden data-type="checkbox">Wajib</th><th data-hidden>Penerangan</th><th data-hidden>Mod pasukan</th></tr></thead><tbody><tr><td>id</td><td>ID Item</td><td>true</td><td>ID unik transaksi</td><td>Semua</td></tr></tbody></table>

#### Contoh Muatan **– Item Dipadam**

```json
{
  "id": 26122826
}
```