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

> **Informasi:** **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 **Jenis autentikasi**. Ada lima 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 |
| **mTLS** | Sertifikat klien, Kunci privat, CA server (opsional) | API Anda hanya menerima panggilan dari klien yang menyajikan sertifikat (mutual TLS). IDCloud menyajikan sertifikat yang Anda berikan pada setiap notifikasi |

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

#### Menyiapkan mTLS

Dengan **mTLS**, IDCloud mengidentifikasi dirinya ke API Anda dengan menyajikan sertifikat klien
(mutual TLS), alih-alih mengirim kunci, password, atau token. API Anda harus dikonfigurasi untuk
meminta sertifikat tersebut dan memercayai siapa yang menerbitkannya. Memilih **mTLS** menampilkan
tiga kolom:

| Kolom | Yang perlu diberikan |
| :- | :- |
| **Sertifikat klien (PEM)** | Rantai sertifikat dalam format PEM, dengan sertifikat leaf di urutan pertama. Tambahkan sertifikat perantara setelah sertifikat Anda, agar API Anda dapat mengaitkan sertifikat tersebut dengan otoritas yang dipercayainya |
| **Kunci privat (PEM)** | Kunci yang berpasangan dengan sertifikat, dalam format PEM dan **tanpa password**. Disimpan dalam bentuk terenkripsi dan tidak pernah ditampilkan lagi |
| **CA server (PEM, opsional)** | Hanya jika sertifikat API Anda sendiri ditandatangani oleh otoritas sertifikat privat. Tanpanya, IDCloud memercayai otoritas publik |

Anda dapat memilih file `.pem` atau menempelkan teksnya. Setiap kolom menerima hingga 20.000
karakter.

Beberapa aturan yang perlu diketahui sebelum memilih mTLS:

- **URL harus HTTPS**, dan API Anda harus menerima TLS 1.2 atau yang lebih baru.
- **Setelah disimpan, jenisnya terkunci.** Jenis autentikasi tidak dapat diubah ke jenis lain di
  halaman ini. Untuk mengganti metode, hubungi dukungan Unico.
- **Tidak ada kredensial lain yang dikirim.** mTLS tidak dapat digabungkan dengan API Key, Basic
  Auth, atau OAuth 2.0 pada webhook yang sama.
- **Pengalihan dianggap sebagai kegagalan.** IDCloud tidak mengikutinya, jadi arahkan URL ke alamat
  akhir.

### 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. Dengan mTLS, IDCloud memvalidasi sertifikat dan kunci sebagai gantinya: keduanya harus dalam
format PEM, kunci tidak boleh memiliki password dan harus cocok dengan sertifikat, dan sertifikat
harus berada dalam masa berlakunya.

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 mengganti sertifikat mTLS sebelum kedaluwarsa?** Edit webhook-nya. Sertifikat dan
kunci privat ditampilkan tersamarkan. Berikan sertifikat baru **dan** kunci privat baru — keduanya
wajib, meskipun hanya salah satunya yang berubah — serta CA server lagi, jika Anda menggunakannya.
Lalu simpan. IDCloud mulai menggunakan sertifikat baru dalam waktu sekitar 5 menit, jadi biarkan
sertifikat sebelumnya tetap berlaku sedikit lebih lama dari itu sebelum mencabutnya. Jika Anda tidak
mengubah ketiga kolom tersebut, sertifikat saat ini tetap digunakan.

**Bisakah saya beralih dari mTLS ke jenis autentikasi lain?** Tidak di halaman ini: setelah
disimpan, jenisnya terkunci. Hubungi dukungan Unico untuk menghapus konfigurasi webhook, lalu buat
kembali dengan metode yang baru.

**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. Dengan mTLS, periksa juga bahwa API Anda memercayai siapa yang
menerbitkan sertifikat, bahwa sertifikat belum kedaluwarsa, dan bahwa CA server sudah diisi jika
sertifikat API Anda berasal dari otoritas privat. 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 | mTLS
         │                             OAuth 2.0: + Auth URL dan Client ID
         │                             mTLS: + Sertifikat klien, Kunci privat, CA server (opsional)
         └─ 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
```