Lewati ke konten utama

Webhook

Markdown

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​

CakupanSatu webhook per tenant dan branch. Tidak ada daftar: jika sudah ada satu yang dikonfigurasi, konfigurasi tersebut akan diedit, bukan digandakan.
Lingkungan terpisahPortal Staging mengonfigurasi webhook UAT; Portal Production mengonfigurasi Production. Mengonfigurasi salah satu tidak memengaruhi yang lain.
Kapan berlakuSegera setelah Anda menyimpan.
Keamanan secretSecret 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

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

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:

TipeKolom yang ditampilkanKapan digunakan
Nonetidak adaAPI 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 KeySecretAPI Anda memvalidasi kunci tetap
Basic AuthSecretAPI Anda menggunakan username dan password, gaya HTTP Basic
OAuth 2.0Auth URL, Client ID, SecretAPI Anda memerlukan token. IDCloud mengambil token dari URL tersebut dan memperbaruinya secara otomatis
mTLSSertifikat 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

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:

KolomYang 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:

KolomYang dikontrolDefault
Maximum retriesBerapa 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 percobaan2s
Maximum time (s)Interval maksimum antar percobaan10s
Maximum duration (s)Berapa lama menunggu per percobaan sebelum dianggap gagal2s
Maximum doublingsFaktor 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

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​

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