Konfigurasi

Untuk mengonfigurasi webhook di Unico IDCloud, berikan endpoint, metode autentikasi, dan kebijakan percobaan ulang. Konfigurasi dilakukan oleh tim Unico — hubungi tim CS / Onboarding Anda untuk mendaftarkan atau memperbarui 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 <encoded> 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 <token>); 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.

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. Semua field bersifat wajib.

{
  "processId": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "state": "PROCESS_STATE_FINISHED",
  "flow": "id",
  "lastEvent": "EVENT_TYPE_PROCESS_CREATED",
  "lastEventDescription": "Process created"
}

Untuk skema payload lengkap dan daftar nilai lastEvent, lihat Jenis event.

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.

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.