Webhook

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 integrasi byUnico maupun byClient.

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 halaman ini ada, setiap perubahan webhook memerlukan tiket dukungan — sekitar 30 tiket per bulan hanya untuk itu. Sekarang Anda dapat melakukannya sendiri, dalam hitungan menit, baik di Staging maupun Production.

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

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.

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.

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

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