# Webhook

<figure><img src="/files/3908072eedfec744a4946f67b9062a0b3d08abbf" alt=""><figcaption></figcaption></figure>

***

## Pendaftaran

Anda boleh mendaftarkan webhook di <mark style="color:biru;">**`Tetapan`**</mark> **>** <mark style="color:biru;">**`Integrasi & API`**</mark> 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:

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

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

### `txs/new`

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

{% hint style="warning" %}
**Nota:** Peristiwa ini *tidak* dicetuskan untuk pelarasan yang dibuat melalui pengeditan 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>Perihalan</th><th data-hidden data-type="checkbox">Adakah perlu</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 dalam sejarah</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 sejarah.</p><ul><li>Masuk : in</li><li>Keluar : out</li><li>Laras : 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 dipadamkan</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 dipadamkan</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 dipadamkan</td><td>false</td><td></td><td></td></tr><tr><td>items</td><td>true</td><td>Item baris dalam transaksi</td><td>true</td><td>Item mengikut produk yang membentuk sejarah</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/laras/pindah</td><td>true</td><td>Kuantiti masuk/keluar/laras/pindah bagi produk tersebut</td><td>Semua mod</td></tr><tr><td>items.deleted</td><td>true</td><td>Sama ada item dipadamkan</td><td>true</td><td>Sama ada produk dipadamkan</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 dipadamkan</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 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` Peristiwa

```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` Peristiwa

<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 yang sedia ada (Stok Masuk / Stok Keluar / Laras Stok / Pindah Stok) **disunting**.

<table><thead><tr><th>Medan</th><th width="100" data-type="checkbox">Diperlukan</th><th>Perihalan</th><th data-hidden data-type="checkbox">Adakah perlu</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 dalam sejarah</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 sejarah.</p><ul><li>Masuk : in</li><li>Keluar : out</li><li>Laras : 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 dipadamkan</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 dipadamkan</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 dipadamkan</td><td>false</td><td></td><td></td></tr><tr><td>items</td><td>true</td><td>Item baris dalam transaksi</td><td>true</td><td>Item mengikut produk yang membentuk sejarah</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/laras/pindah bagi produk tersebut</td><td>Semua mod</td></tr><tr><td>items.deleted</td><td>true</td><td>Sama ada item dipadamkan</td><td>true</td><td>Sama ada produk dipadamkan</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 dipadamkan</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 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>revision</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,
  "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,
  "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

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

### `item/new`

Dihantar apabila item baharu ditambah ke inventori pasukan.

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

<table><thead><tr><th width="318">Medan</th><th>Perihalan</th><th data-hidden data-type="checkbox">Adakah perlu</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 dalam sejarah</td><td>Semua</td></tr><tr><td>nama</td><td>Nama Item</td><td>true</td><td><p>Jenis sejarah.</p><ul><li>Masuk : in</li><li>Keluar : out</li><li>Laras : 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>attrs</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**: Peristiwa ini *tidak* dicetuskan *f*or pengeditan pukal yang dibuat melalui <mark style="color:biru;">**`Pusat Data`**</mark>**&#x20;>&#x20;**<mark style="color:biru;">**`Item`**</mark> atau melalui <mark style="color:biru;">**`Import Excel`**</mark> fungsi.
{% endhint %}

<table><thead><tr><th width="318">Medan</th><th>Perihalan</th><th data-hidden data-type="checkbox">Adakah perlu</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 dalam sejarah</td><td>Semua</td></tr><tr><td>nama</td><td>Nama Item</td><td>true</td><td><p>Jenis sejarah.</p><ul><li>Masuk : in</li><li>Keluar : out</li><li>Laras : 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>attrs</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 dipadamkan daripada inventori pasukan.

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

<table><thead><tr><th width="318">Medan</th><th>Perihalan</th><th data-hidden data-type="checkbox">Adakah perlu</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 dalam sejarah</td><td>Semua</td></tr></tbody></table>

#### Contoh Muatan **– Item Dipadamkan**

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://www.boxhero.io/docs/documentation/ms/integrasi/open-api/webhook.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.