---
title: Webhook
description: Konfigurasikan ke mana IDCloud memberi tahu sistem Anda saat status perjalanan berubah, bagaimana sistem tersebut melakukan autentikasi terhadap API Anda, dan apa yang terjadi jika API Anda tidak merespons.
canonical: https://developer.unico.io/id/dual-api/product-guide/portal-idcloud/settings/webhook
locale: id
generated_by: markdown-export
---

**Webhook** adalah cara IDCloud secara otomatis memberi tahu sistem Anda saat sesuatu terjadi dalam
perjalanan verifikasi identitas. Alih-alih sistem Anda bertanya "apakah sudah selesai?", IDCloud
memanggil API Anda pada saat peristiwa itu terjadi.

Di halaman ini Anda menetapkan alamat API Anda, cara IDCloud melakukan autentikasi terhadapnya, dan
apa yang terjadi jika API tidak merespons.

:::info
**Untuk siapa:** pelanggan yang ingin menerima hasil perjalanan secara otomatis, tanpa polling.
Berlaku untuk semua jenis integrasi.

**Apa yang berubah di sistem Anda:** sistem Anda kini menerima notifikasi pada setiap perubahan
status, bukan lagi harus melakukan polling ke IDCloud.

**Di mana menemukannya:** Portal IDCloud → sidebar **Settings** → tab **Webhook**.
:::

## Sebelum Anda mulai

### Izin akses

Pengguna Anda memerlukan profil **Configurator** — profil yang sama yang memberikan akses ke
Journey Customization. Jika tab Webhook tidak muncul, hubungi administrator akun Anda.

### Bagaimana konfigurasi diterapkan

| | |
| :- | :- |
| **Cakupan** | Satu webhook per **tenant dan branch**. Tidak ada daftar: jika sudah ada satu yang dikonfigurasi, konfigurasi tersebut akan diedit, bukan digandakan. |
| **Lingkungan terpisah** | Portal Staging mengonfigurasi webhook UAT; Portal Production mengonfigurasi Production. Mengonfigurasi salah satu tidak memengaruhi yang lain. |
| **Kapan berlaku** | Segera setelah Anda menyimpan. |
| **Keamanan secret** | Secret dienkripsi dan tidak pernah ditampilkan lagi dalam bentuk teks biasa. Di layar, secret selalu disamarkan. |

### Yang perlu disiapkan

- **URL HTTPS** dari API Anda yang akan menerima notifikasi. URL tersebut harus sudah aktif dan
  menerima permintaan sebelum Anda menyimpan.
- **Kredensial** yang diharapkan oleh API Anda, berdasarkan metode autentikasi yang Anda pilih
  (lihat Langkah 3).
- Jika API Anda memiliki batas kapasitas, jumlah **permintaan per detik** yang didukungnya.

### Yang perlu diputuskan sebelumnya

Dua keputusan teknis bergantung pada siapa yang mengelola API Anda, bukan pada siapa yang
mengoperasikan Portal. Perlu diselaraskan sebelum membuka halaman ini:

- **Metode autentikasi mana** yang diperlukan API Anda.
- **Apakah Anda akan menyesuaikan retries** atau membiarkannya sesuai default. Default bekerja
  untuk sebagian besar kasus.

## Langkah demi langkah

### Langkah 1 — Buka tab Webhook

Di Portal IDCloud, klik **ikon roda gigi (Settings)** pada sidebar dan pilih tab **Webhook**.

Jika Anda belum memiliki webhook yang dikonfigurasi, halaman akan menampilkan **"No webhooks
created"** dan tombol **Create webhook**. Jika Anda sudah memilikinya, halaman menampilkan kartu
**Your webhook** dengan endpoint, jenis autentikasi, dan secret yang disamarkan, ditambah tombol
**Configure webhook** untuk mengeditnya.

![Kartu manage webhook Anda, dengan tombol Configure webhook](/img/product-guide/webhook/en/01-manage-webhook.png)

*Kartu "Your webhook" dengan endpoint, jenis autentikasi, dan secret yang disamarkan.*

### Langkah 2 — Masukkan URL API Anda

Klik **Create webhook** (atau **Configure webhook**, jika sudah ada) dan isi kolom **Client URL
(Endpoint)**, di bagian "Client information".

Ini adalah alamat tempat IDCloud akan mengirim notifikasi. Alamat ini harus **HTTPS**.

**Arahkan ke alamat yang sudah aktif.** IDCloud mulai memanggil URL ini segera setelah Anda
menyimpan. Jika URL tersebut belum ada, notifikasi pertama akan gagal dan menghabiskan retries
sebelum tim Anda menyadarinya.

![Kolom Endpoint, dengan teks bantuan tentang persyaratan HTTPS](/img/product-guide/webhook/en/02-edit-webhook.png)

*Kolom Endpoint, dengan teks bantuan tentang persyaratan HTTPS.*

### Langkah 3 — Pilih cara IDCloud melakukan autentikasi terhadap API Anda

Di bagian "Authentication", pilih **Authentication type**. Ada empat opsi, dan masing-masing
meminta kolom yang berbeda:

| Tipe | Kolom yang ditampilkan | Kapan digunakan |
| :- | :- | :- |
| **None** | tidak ada | API Anda tidak memerlukan autentikasi. Gunakan ini hanya jika API memiliki perlindungan lain — tanpa autentikasi, siapa pun yang menemukan URL tersebut dapat mengirim data ke sana |
| **API Key** | Secret | API Anda memvalidasi kunci tetap |
| **Basic Auth** | Secret | API Anda menggunakan username dan password, gaya HTTP Basic |
| **OAuth 2.0** | Auth URL, Client ID, Secret | API Anda memerlukan token. IDCloud mengambil token dari URL tersebut dan memperbaruinya secara otomatis |

Untuk **OAuth 2.0**, **Auth URL** adalah alamat tempat IDCloud mengambil token — bukan URL yang
menerima notifikasi. Keduanya adalah alamat yang berbeda, dan menukarnya adalah kesalahan paling
umum di halaman ini.

**Secret** disimpan dalam bentuk terenkripsi. Saat mengedit webhook yang sudah ada, kolom ini akan
tampak kosong: mengisinya akan menimpa secret saat ini, dan membiarkannya kosong akan
mempertahankan nilai yang sudah ada.

**Konfirmasikan metode ini dengan siapa yang mengelola API Anda sebelum menyimpan.** Autentikasi
yang salah tidak akan menghasilkan error di layar — tetapi menghasilkan notifikasi yang gagal
secara diam-diam setelahnya, dan Anda baru menyadarinya ketika sebuah hasil tidak pernah sampai.

![Kolom Authentication type dan kolom kredensial yang sesuai](/img/product-guide/webhook/en/02-edit-webhook.png)

*Kolom Authentication type dan kolom kredensial yang sesuai.*

### Langkah 4 — Sesuaikan retries, jika perlu

Bagian **Retry configuration** bersifat **opsional** dan awalnya dimatikan. Aktifkan hanya jika
Anda perlu mengubah perilaku default.

Mengaktifkannya menampilkan enam kolom:

| Kolom | Yang dikontrol | Default |
| :- | :- | :- |
| **Maximum retries** | Berapa kali IDCloud mencoba lagi sebelum berhenti | — |
| **Rate limit (req/s)** | Jumlah maksimum notifikasi per detik. Turunkan jika API Anda memiliki kapasitas terbatas | — |
| **Minimum time (s)** | Interval minimum antar percobaan | 2s |
| **Maximum time (s)** | Interval maksimum antar percobaan | 10s |
| **Maximum duration (s)** | Berapa lama menunggu per percobaan sebelum dianggap gagal | 2s |
| **Maximum doublings** | Faktor pertumbuhan interval antar percobaan (backoff) | 5 |

Perilaku gabungannya: IDCloud mencoba, menunggu selama **minimum time**, mencoba lagi, dan terus
meningkatkan interval sesuai **maximum doublings** hingga mencapai **maximum time** — berulang
sampai **maximum retries**. Setiap percobaan individu berhenti setelah **maximum duration**.

**Sesuaikan Rate limit sebelum mengubah apa pun yang lain.** Jika API Anda mengalami kegagalan
akibat beban, masalahnya adalah throughput, bukan retries — dan meningkatkan retries dalam
skenario tersebut justru memperburuk keadaan, karena melipatgandakan jumlah panggilan. Turunkan
rate terlebih dahulu.

**Meningkatkan Maximum retries tidak menggantikan API yang stabil.** Retries mencakup
ketidaktersediaan sesaat. Jika API Anda sering gagal, pengaturan ini hanya menunda saat Anda
kehilangan notifikasi.

![Enam kolom retry, ditampilkan setelah toggle diaktifkan](/img/product-guide/webhook/en/02-edit-webhook.png)

*Enam kolom retry, ditampilkan setelah toggle diaktifkan.*

### Langkah 5 — Simpan

Klik **Save**. **Cancel** membatalkan semua perubahan dan mempertahankan konfigurasi sebelumnya.

IDCloud memvalidasi token URL sebelum mengizinkan Anda menyimpan, ketika metodenya adalah OAuth
2.0.

Setelah menyimpan, kartu **Your webhook** menampilkan endpoint dan jenis autentikasi. Secret akan
ditampilkan tersamarkan dan tidak dapat diambil kembali dari layar — jika Anda kehilangan
nilainya, Anda perlu menetapkan yang baru.

**Lakukan uji coba nyata sebelum menganggapnya selesai.** Mulai sebuah perjalanan di Staging dan
konfirmasikan notifikasi sampai ke API Anda. Halaman ini hanya mengonfirmasi bahwa konfigurasi
telah disimpan, bukan bahwa API Anda telah menerimanya.

## FAQ

**Bisakah saya mendaftarkan lebih dari satu webhook?** Tidak. Hanya satu webhook per tenant dan
branch. Jika sudah ada satu, webhook tersebut akan diedit — tidak ada cara untuk membuat yang
kedua.

**Saya mengonfigurasinya di Staging. Apakah berlaku juga untuk Production?** Tidak. Kedua
lingkungan tersebut independen: Portal Staging mengonfigurasi webhook UAT, dan Portal Production
mengonfigurasi Production. Anda perlu mengulang konfigurasi tersebut di Portal Production.

**Bagaimana saya bisa melihat secret yang saya daftarkan?** Anda tidak bisa. Secret dienkripsi
saat disimpan dan selalu ditampilkan tersamarkan. Jika Anda kehilangan nilainya, daftarkan yang
baru melalui kolom Secret — mengisinya akan menimpa yang sebelumnya.

**Saya mengedit webhook tetapi tidak ingin mengubah secret. Apa yang harus saya lakukan?**
Biarkan kolom Secret kosong. Nilai saat ini akan dipertahankan.

**Bagaimana saya menghapus webhook?** Halaman ini tidak menyediakan opsi penghapusan. Untuk
menghapus konfigurasi, hubungi dukungan Unico. Jika tujuannya hanya berhenti menerima notifikasi
atau mengubah tujuan, edit URL-nya saja.

**Saya sudah menyimpan tetapi notifikasi tidak sampai.** Periksa, dalam urutan ini: URL sudah
benar dan berupa HTTPS; API Anda aktif; metode autentikasi sesuai dengan yang diharapkan; dan
secret dimasukkan dengan benar. Kegagalan autentikasi tidak muncul sebagai error di halaman ini —
kegagalan tersebut terjadi pada saat pengiriman.

**Apa perbedaan antara "Maximum duration" dan "Maximum time"?** "Maximum time" adalah interval
terpanjang **antara** dua percobaan. "Maximum duration" adalah berapa lama IDCloud menunggu
**per** percobaan sebelum menganggapnya gagal.

**Apakah saya perlu webhook jika saya sudah melakukan polling untuk hasil melalui API?** Tidak
wajib, tetapi ini menghemat sistem Anda dari harus melakukan polling. Jika Anda sudah memiliki
rutinitas polling yang berjalan baik, webhook menjadi optimisasi, bukan kebutuhan.

## Referensi cepat

```text
Portal IDCloud
 └─ Settings (ikon roda gigi di sidebar)
     └─ Tab Webhook
         ├─ Client information ....... Client URL (Endpoint), HTTPS
         ├─ Authentication ............ None | API Key | Basic Auth | OAuth 2.0
         │                             OAuth 2.0: + Auth URL dan Client ID
         └─ Retries (opsional) ....... Maximum retries
                                       Rate limit (req/s)
                                       Minimum time (2s) · Maximum time (10s)
                                       Maximum duration (2s) · Maximum doublings (5)

Satu webhook per tenant dan branch · UAT dan Production independen · Secret tidak pernah ditampilkan · Cancel · Save
```