> For the complete documentation index, see [llms.txt](https://www.boxhero.io/docs/llms.txt). Every page is available as Markdown by appending `.md` to its URL; this page is [Markdown](https://www.boxhero.io/docs/id/developers/webhooks/overview.md).

# Ringkasan

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

![](https://assets.boxhero.io/docs/images/e073efd69a551d1c50313ce8969f89656fe7fb6c2f4bf97cd67eb7398f4e21d6-1601x941.jpeg)

---

## Pendaftaran

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

![](https://assets.boxhero.io/docs/images/39738e2bf18459a1ba1d9df4c6a3eb786fc434f5fab37932e8edf50bf6a0b91a-1100x810.png)

## 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.
- Setiap **respons selain 2xx** dianggap gagal dan akan dicoba ulang.

## Struktur Payload Webhook

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

```json
{
  "id": "3f9a2b7c-6d4e-4a1f-9c8b-2e5d7a0f1b34", // Event's unique ID
  "topic": "txs/new", // Event topic
  "version": 1, // Payload schema version
  "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 untuk transaksi yang diedit dan dihapus (`txs/edit`, `txs/delete`) juga menyertakan `revision`, sehingga Anda dapat mengetahui versi transaksi mana yang dijelaskan oleh suatu peristiwa.

## Topik Peristiwa

> **Note**
>
> Jika Anda memerlukan dukungan untuk topik peristiwa lainnya, silakan hubungi [Kontak](https://www.boxhero.io/docs/id/resources/contact).

### txs/new

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

> **Caution**
>
> **Catatan:** Peristiwa ini _tidak_ dipicu untuk penyesuaian yang dibuat melalui edit massal atau impor (misalnya saat menambahkan atau memperbarui barang melalui Excel).

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

#### Contoh Payload Webhook – Peristiwa Stock In

```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 Payload Webhook – Peristiwa Move Stock

```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": "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

```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 Payload Webhook – Transaksi Move Stock yang Diedit

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

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

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

### item/new

Dikirim saat barang baru ditambahkan ke stok tim.

> **Caution**
>
> **Catatan**: Peristiwa ini _tidak_ dipicu saat menggunakan fitur `Tambah Varian Barang` atau saat mengimpor barang melalui `Impor dari Excel`.

| 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

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

Dikirim saat barang yang sudah ada diedit.

> **Caution**
>
> **Catatan**: Peristiwa ini _tidak_ dipicu untuk edit massal yang dilakukan melalui `Kelola Data` > `Barang` atau melalui fungsi `Impor dari Excel`.

| 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

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

Dikirim saat barang dihapus dari stok tim.

> **Caution**
>
> **Catatan**: Peristiwa ini _tidak_ dipicu untuk penghapusan massal yang dilakukan melalui `Kelola Data` > `Barang`.

| Field | Deskripsi |
| --- | --- |
| id | ID barang |

#### Contoh Payload – Barang Dihapus

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