--- title: Konfigurasi description: Panduan langkah demi langkah untuk mengonfigurasi webhook IDCloud — konfigurasi mandiri melalui portal untuk Web dan SDK, serta konfigurasi per klien untuk integrasi API menggunakan orkestrasi Check (khusus Brasil). canonical: https://developer.unico.io/id/dual-api/developers/webhooks-and-events/setup locale: id generated_by: markdown-export --- IDCloud mendukung dua modalitas webhook, tergantung cara Anda berintegrasi: - **Via Portal** — untuk integrasi Web dan SDK. Konfigurasi mandiri langsung di portal IDCloud. - **By client** — untuk integrasi API menggunakan kemampuan **orkestrasi Check** (alur asinkron). Dikonfigurasi oleh tim Unico. Tersedia **khusus di Brasil**. ### Via Portal (Web & SDK) Untuk mendaftarkan atau memperbarui endpoint webhook Anda, akses portal IDCloud dan navigasikan ke **Pengaturan > Webhook**. #### Informasi yang diperlukan | Field | Deskripsi | |---|---| | **Notification URL** | Endpoint yang akan dipanggil Unico untuk mengirimkan notifikasi event. Harus dapat diakses melalui HTTPS. | | **Authentication type** | Cara Unico mengautentikasi terhadap endpoint Anda. Lihat opsi di bawah. | | **Retry settings** | Jumlah maksimum percobaan dan interval antar percobaan (backoff eksponensial diterapkan). | | **Concurrency limit** | Jumlah maksimum pengiriman yang sedang berlangsung secara bersamaan (maks: **500**). | | **Timeout** | Waktu tunggu maksimum untuk respons endpoint, dalam detik. | | **Status to notify** | Kumpulan status proses yang memicu notifikasi. Saat ini ditetapkan ke `PROCESS_STATE_FINISHED`; tidak dapat dikonfigurasi saat ini. | #### Metode autentikasi ****OAuth2**** Berikan: - Webhook `endpoint` - OAuth2 provider `URL` - OAuth2 provider `ClientId` - OAuth2 provider `Secret` Unico akan meminta access token dari URL provider menggunakan client credentials dan meneruskannya ke endpoint Anda sebagai Bearer token. ****Basic Authorization**** Berikan kredensial dalam format `user:pass`. Unico mengenkodenya dalam Base64 dan mengirimkannya di header `Authorization: Basic ` pada setiap panggilan webhook. ****API Key**** Dua format didukung. String dipisahkan pada **tanda titik dua pertama**: - `header:value` — menetapkan nama header kustom. Contoh: - `X-API-Key:abc123` → `X-API-Key: abc123` - `Authorization:Bearer abc123` → `Authorization: Bearer abc123` - `value` saja (tanpa titik dua) — nilai dikirim sebagai header `Authorization` tanpa awalan skema. Contoh: `abc123` → `Authorization: abc123`. Gunakan format `header:value` jika Anda memerlukan skema Bearer (misalnya, `Authorization:Bearer `); format nilai saja mengirim nilai mentah tanpa awalan. ****Tanpa autentikasi**** Tidak ada kredensial yang dikirim. Hanya direkomendasikan untuk lingkungan pengembangan — endpoint produksi harus selalu memerlukan autentikasi. #### Status proses yang memicu notifikasi Saat ini, Unico mengirimkan notifikasi setiap kali proses bertransisi ke: | State | Deskripsi | |---|---| | `PROCESS_STATE_FINISHED` | Proses selesai — status terminal, terlepas dari hasilnya. | :::warning[Status dapat berkembang] Kumpulan status yang diberitahukan oleh platform dapat berubah di masa mendatang. Buat status yang direspons oleh endpoint Anda **dapat dikonfigurasi**, sehingga menambahkan status baru tidak memerlukan deploy ulang layanan Anda. ::: #### Format permintaan Pengiriman webhook adalah permintaan **POST** ke endpoint Anda. Body berisi identifier proses dan status saat ini. ```json { "processId": "8263a268-5388-492a-bca2-28e1ff4a69f0", "state": "PROCESS_STATE_FINISHED", "flow": "id" } ``` :::note[`lastEvent` dan `lastEventDescription`] Dua field ini muncul dalam payload **hanya ketika proses kedaluwarsa** sebelum pengguna menyelesaikan perjalanan. Keduanya tidak ada dalam payload penyelesaian normal. Lihat [Jenis event](/developers/webhooks-and-events/event-types) untuk skema lengkap dan daftar nilai `lastEvent` yang mungkin. ::: #### Respons yang diharapkan Endpoint Anda harus merespons **secara sinkron**: - **Berhasil**: status HTTP apa pun dalam rentang `200`–`299`. - **Gagal**: status lainnya. Unico akan mencoba ulang dengan backoff eksponensial hingga jumlah maksimum percobaan yang dikonfigurasi, atau sampai `2xx` diterima. :::tip[Respons cepat] Akui webhook dengan cepat (dalam timeout yang dikonfigurasi) dan proses payload secara asinkron di sisi Anda. Pemrosesan yang lama di dalam handler webhook meningkatkan kemungkinan timeout dan percobaan ulang yang tidak perlu. ::: Untuk panduan idempotency dan penanganan percobaan ulang, lihat [Keamanan](/developers/webhooks-and-events/security). ### By client (API — Khusus Brasil) :::info[Khusus Brasil] Webhook by-client tersedia secara eksklusif untuk integrasi API di Brasil yang menggunakan kemampuan **orkestrasi Check** — alur asinkron di mana hasil proses dikirimkan melalui webhook, bukan sebagai respons API sinkron. ::: Untuk mendaftarkan atau memperbarui endpoint Anda, hubungi tim **CS / Onboarding** Anda. #### Informasi yang diperlukan | Field | Deskripsi | |---|---| | **Notification URL** | Endpoint yang diekspos sistem Anda untuk menerima pembaruan status. Harus dapat diakses melalui HTTPS. | | **Authentication type** | Cara Unico mengautentikasi terhadap endpoint Anda. Lihat opsi di bawah. | | **Retry settings** | Jumlah maksimum percobaan dan interval antar percobaan (backoff eksponensial diterapkan). | | **Concurrency limit** | Jumlah maksimum pengiriman yang sedang berlangsung secara bersamaan (maks: **500**). | | **Timeout** | Waktu tunggu maksimum untuk respons endpoint, dalam detik. | #### Metode autentikasi ****OAuth2**** Berikan: - Webhook `endpoint` - OAuth2 provider `URL` - OAuth2 provider `ClientId` - OAuth2 provider `Secret` Unico akan meminta access token dari URL provider menggunakan client credentials dan meneruskannya ke endpoint Anda sebagai Bearer token. ****Basic Authorization**** Berikan kredensial dalam format `user:pass`. Unico mengenkodenya dalam Base64 dan mengirimkannya di header `Authorization: Basic ` pada setiap panggilan webhook. ****API Key**** Dua format didukung. String dipisahkan pada **tanda titik dua pertama**: - `header:value` — menetapkan nama header kustom. Contoh: - `X-API-Key:abc123` → `X-API-Key: abc123` - `Authorization:Bearer abc123` → `Authorization: Bearer abc123` - `value` saja (tanpa titik dua) — nilai dikirim sebagai header `Authorization` tanpa awalan skema. Contoh: `abc123` → `Authorization: abc123`. Gunakan format `header:value` jika Anda memerlukan skema Bearer (misalnya, `Authorization:Bearer `); format nilai saja mengirim nilai mentah tanpa awalan. ****Tanpa autentikasi**** Tidak ada kredensial yang dikirim. Hanya direkomendasikan untuk lingkungan pengembangan — endpoint produksi harus selalu memerlukan autentikasi. #### Kode status Webhook by-client menggunakan **kode status numerik**: | Kode | Deskripsi | |---|---| | `2` | Divergensi — proses selesai dengan divergensi pada pemeriksaan identitas. | | `3` | Selesai — proses berhasil diselesaikan. | | `5` | Error — proses berakhir karena terjadi kesalahan. | #### Format permintaan Pengiriman webhook adalah permintaan **POST** ke endpoint Anda. Body berisi identifier transaksi dan kode status numerik. ```json { "id": "8263a268-5388-492a-bca2-28e1ff4a69f0", "status": 3 } ``` #### Respons yang diharapkan Endpoint Anda harus merespons **secara sinkron**: - **Berhasil**: status HTTP apa pun dalam rentang `200`–`299`. - **Gagal**: status lainnya. Unico akan mencoba ulang dengan backoff eksponensial hingga jumlah maksimum percobaan yang dikonfigurasi, atau sampai `2xx` diterima. :::tip[Respons cepat] Akui webhook dengan cepat (dalam timeout yang dikonfigurasi) dan proses payload secara asinkron di sisi Anda. Pemrosesan yang lama di dalam handler webhook meningkatkan kemungkinan timeout dan percobaan ulang yang tidak perlu. ::: :::warning[Pengiriman setidaknya satu kali] Platform menjamin pengiriman setidaknya satu kali — notifikasi yang sama mungkin tiba lebih dari sekali. Implementasikan idempotency di sisi Anda menggunakan field `id` untuk menangani duplikat dengan aman. Untuk panduan idempotency dan penanganan percobaan ulang, lihat [Keamanan](/developers/webhooks-and-events/security). :::