> ## Documentation Index
> Fetch the complete documentation index at: https://foliant-help.iforiti.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kirim webhook ke sistem Anda sendiri

> Integrasi Webhooks mengirim event JSON bertanda tangan ke endpoint Anda sendiri saat Foliant membuat dokumen atau menyelesaikan ekspor.

Integrasi **Webhooks** ditujukan untuk developer. Integrasi ini mengirim event JSON ke alamat HTTPS pilihan Anda setiap kali sesuatu terjadi di Foliant. Dengan begitu, sistem Anda sendiri dapat merespons, misalnya dengan mengarsipkan setiap PDF faktur atau mengambil ekspor yang sudah selesai.

Webhooks masih dalam tahap beta. Jika Anda tidak melihatnya di **Pengaturan › Integrasi**, fitur ini belum tersedia untuk toko Anda. Hubungi dukungan untuk menanyakan akses.

## Event

| Event | Dikirim saat |
| - | - |
| `document.generated` (**Document generated**) | Foliant membuat dokumen untuk pesanan: unduhan, ekspor, atau email pengiriman PDF. |
| `export.completed` (**Export completed**) | Ekspor massal sudah siap. |

## Hubungkan webhook

1. Di Foliant, buka **Pengaturan › Integrasi**.

2. Di **Webhooks**, klik **Hubungkan**.

3. Isi pengaturannya:

   | Kolom | Yang perlu diisi |
   | - | - |
   | **Endpoint URL** | Alamat tujuan pengiriman event dari Foliant. Alamat ini harus menggunakan HTTPS, misalnya `https://example.com/webhooks/foliant`. |
   | **Signing secret** | Opsional. Dengan secret, setiap permintaan diberi tanda tangan sehingga Anda dapat memastikan permintaan itu berasal dari Foliant. |
   | **Events** | Event yang akan dikirim. Keduanya dipilih secara default. |

4. Klik **Hubungkan**.

Anda dapat mengubah URL, secret, dan event nanti di **Pengaturan** pada halaman integrasi.

## Isi setiap permintaan

Foliant mengirim permintaan `POST` dengan body JSON:

```json theme={null}
{
  "id": "a unique delivery id",
  "event": "document.generated",
  "created_at": "2026-10-11T09:30:00+00:00",
  "shop": "your-store.myshopify.com",
  "data": { }
}
```

### Data `document.generated`

* `template`: `uuid` dan `name` template.
* `document_type`: `invoice`, `credit_note`, `quote`, atau kosong untuk dokumen lain.
* `order`: `id`, `name`, dan `type` pesanan (pesanan atau draf pesanan).
* `refund_id` dan `fulfillment_id`, jika dokumen tersebut untuk pengembalian dana atau pengiriman.
* `document_number` dan `issued_at`, untuk dokumen bernomor.
* `source`: cara dokumen dibuat, misalnya `download`, `admin_download`, `export`, atau `email`.
* `export`: ID ekspor, jika dokumen tersebut bagian dari ekspor.
* `generated_at`.

### Data `export.completed`

* `export`: `uuid`, `order_type`, `template_uuids`, jumlah `orders`, `orders_skipped` (dihapus setelah dipilih) dan `documents`, `requested_by` (`merchant` atau `customer`), serta `completed_at`.
* `download_url`: tautan untuk mengunduh ekspor, dan `download_url_expires_at`, waktu tautan tersebut berhenti berfungsi.
* `download_expires_at`: waktu ekspor itu sendiri kedaluwarsa.

Event berisi ID dan jumlah, bukan alamat email pelanggan.

### Header

| Header | Isi |
| - | - |
| `X-Foliant-Event` | Event-nya, misalnya `document.generated`. |
| `X-Foliant-Delivery` | ID unik pengiriman (sama dengan `id` di body). |
| `X-Foliant-Timestamp` | Waktu pengiriman, dalam detik Unix. |
| `X-Foliant-Signature` | `sha256=` diikuti tanda tangan. Hanya ada jika Anda mengatur signing secret. |

## Periksa tanda tangan

Tanda tangan adalah HMAC-SHA256 dalam format hex dari timestamp, sebuah titik, dan body permintaan mentah (`<timestamp>.<body>`), dengan signing secret Anda sebagai kuncinya. Hitung tanda tangan di sisi Anda, lalu bandingkan dengan nilai setelah `sha256=` di `X-Foliant-Signature`. Gunakan body mentah persis seperti yang diterima.

## Respons dan percobaan ulang

* Setiap respons 2xx dianggap terkirim.
* Jika endpoint Anda mengembalikan error 5xx, 408 atau 429, atau tidak merespons dalam 10 detik, Foliant akan mencoba lagi nanti dengan jeda yang makin lama setiap kali, hingga 5 kali percobaan.
* Respons 4xx lainnya bersifat final: Foliant tidak mencobanya lagi.
* Setiap event dikirim satu kali per dokumen atau ekspor. Percobaan ulang tidak pernah mengirimnya dua kali setelah berhasil.

Setiap pengiriman ditampilkan di **Aktivitas** pada halaman integrasi. Di sana Anda dapat memilih **Coba lagi** untuk pengiriman yang gagal. Lihat [Aktivitas integrasi](https://foliant-help.iforiti.com/id/integrations/integration-activity.md).

## Artikel terkait

* [Hubungkan dan kelola integrasi](https://foliant-help.iforiti.com/id/integrations/connect-an-integration.md)
* [Aktivitas integrasi](https://foliant-help.iforiti.com/id/integrations/integration-activity.md)
* [Otomatiskan dengan Shopify Flow](https://foliant-help.iforiti.com/id/integrations/shopify-flow.md)
* [Ekspor PDF](https://foliant-help.iforiti.com/id/exports/export-pdfs.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.