Lewati ke konten utama

Webhook

Artikel GetProcess dalam dokumentasi ini menjelaskan cara mendapatkan status suatu proses melalui panggilan ke sebuah endpoint. Dengan cara ini, polling dilakukan untuk menerima informasi tentang proses yang telah dibuat. Ini berarti endpoint dapat dipanggil berkali-kali untuk proses yang sama guna mendapatkan status terbaru.

Dengan menggunakan webhook, dimungkinkan untuk memberi tahu endpoint tertentu setiap kali status suatu proses berubah.

Apa itu webhook?​

Webhook adalah layanan notifikasi sistemik yang memungkinkan integrasi asinkron antar sistem, di mana satu sistem memberi tahu sistem lain melalui sebuah trigger. Dengan cara ini, webhook dapat menjaga sistem tetap mendapatkan informasi terbaru tanpa perlu polling terus-menerus untuk memeriksa pembaruan.

Cara mengonfigurasi Webhook​

Untuk mengonfigurasi webhook, informasi berikut diperlukan:

  • Notification URL: Ini adalah endpoint yang digunakan oleh Unico untuk notifikasi pembaruan status.
  • Authentication Type: Ini adalah metode yang digunakan untuk mengautentikasi pemanggilan endpoint. Opsi berikut tersedia:
    • OAuth2;
    • Basic Authorization;
    • API Key;
    • Tanpa autentikasi.
  • Untuk OAuth2, informasi berikut perlu diberikan:
    • endpoint Webhook;
    • URL penyedia OAuth2;
    • ClientId penyedia OAuth2;
    • Secret penyedia OAuth2.
  • Untuk Basic Authorization, perlu dikirim dalam format user:pass.
  • Untuk API Key, dua format dimungkinkan:
    • header:value, ketika nama header tertentu diinginkan;
    • value, ketika header yang diinginkan adalah Authorization.
  • Retry Settings: Ini menunjukkan jumlah percobaan jika terjadi kegagalan saat memanggil endpoint:
    • Jumlah maksimum percobaan;
    • Interval antar percobaan (dalam detik);
    • Rate Limit: Jumlah maksimum pengiriman simultan (maks: 500);
    • Timeout: Waktu tunggu maksimum untuk respons endpoint (dalam detik).
  • Status yang akan diberitahukan: Anda dapat berlangganan status tertentu untuk menerima notifikasi. Ini meliputi:
    • approved: Transaksi disetujui;
    • processing: Transaksi sedang diproses;
    • inconclusive: Kami tidak dapat melakukan validasi yang konklusif;
    • shared: Transaksi dibagikan, menunggu pengiriman;
    • skipped: Orang tersebut melewati pengambilan biometrik dalam alur;
    • unknown-share: Orang tersebut menandai bahwa mereka tidak mengenali pembelian tersebut;
    • absent-holder: Pemegang kartu tidak hadir untuk melakukan pengambilan;
    • expired: Orang tersebut tidak menyelesaikan pengambilan dalam waktu yang ditentukan dan transaksi kedaluwarsa.
Tentang autentikasi

API dapat dilindungi dengan metode autentikasi seperti Basic Authentication atau API Key. Daftar IP yang valid untuk akses juga dapat ditentukan untuk perlindungan tambahan.

Integrasi dengan Verifikasi Kartu Tidak Hadir​

Saat mengonfigurasi webhook pada platform, Anda dapat menerima informasi tentang proses melalui notifikasi yang dikirim ke endpoint API yang Anda kembangkan untuk menerima pembaruan ini.

Informasi yang dikirim oleh platform ke API meliputi:

  • ID: ID transaksi;
  • Status: Status transaksi;
  • HasIdentityChanged: Apakah terjadi perubahan identitas dalam transaksi (opsional).
catatan

Perhatikan bahwa dimungkinkan untuk memilih status yang ingin diberitahukan kepada klien melalui konfigurasi webhook. Setelah mengirimkan informasi ini, respons yang diharapkan harus bersifat sinkron.

Permintaan​

Permintaan harus berupa metode POST ke REST API, sehingga pengiriman informasi menjadi lebih mudah dan aman. Semua field wajib diisi. Body permintaan harus menerima ID dan status transaksi, seperti contoh berikut:

{
  "id": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "status": "approved",
  "hasIdentityChanged": false
}

Respons​

Respons harus bersifat sinkron. Status untuk permintaan yang berhasil harus berada dalam rentang 200 hingga 299. Status lain akan dianggap sebagai kegagalan, dan Verifikasi Kartu Tidak Hadir akan melakukan percobaan notifikasi tambahan (dengan exponential backoff di antaranya), hingga menerima respons 2xx atau mencapai jumlah maksimum percobaan.

Status Respons​

Saat ini, kami memiliki sekumpulan status, tetapi kumpulan ini dapat berubah di masa mendatang. Oleh karena itu, disarankan untuk membuat status yang diminati klien dapat dikonfigurasi agar dapat mengambil tindakan. Misalnya, jika tujuannya adalah mengambil tindakan setiap kali pengambilan berhasil diselesaikan, saat ini hal ini terjadi dengan status "processing". Namun, karena ini dapat diubah di masa mendatang, disarankan agar status yang menunjukkan keberhasilan pengambilan dapat dikonfigurasi dalam sistem, sehingga perubahan status menjadi "captured" di masa mendatang dapat diterapkan dengan mudah.

Selain itu, kami menyarankan untuk memiliki tindakan khusus untuk status tertentu dan tindakan umum jika status tidak dikenali (misalnya, dengan asumsi bahwa apa pun yang berbeda dari "processing" dan "approved" bersifat tidak konklusif). Hal ini penting karena status baru dapat muncul di masa mendatang, dan webhook tidak diharapkan mengalami kegagalan karena hal ini.

Pertimbangan Penting​

Perhatikan aspek-aspek berikut saat mengembangkan API yang akan digunakan Verifikasi Kartu Tidak Hadir untuk memberi tahu perubahan status:

Rate limit — Untuk menghindari kelebihan beban pada sumber daya Anda dalam situasi dengan banyak transaksi, dimungkinkan untuk menentukan batas atas jumlah kali endpoint dapat dipanggil.

Error Rate — Tingkat kesalahan (respons di luar rentang [200, 299]) harus selalu dijaga tetap rendah. Jika tidak, throughput webhook akan otomatis dikurangi, dan pengurangan ini, dikombinasikan dengan mekanisme percobaan ulang, dapat mengakibatkan peningkatan waktu eksekusi untuk webhook baru.

Idempotence — Implementasi webhook saat ini menjamin pengiriman minimal satu kali (at-least-once), sehingga status yang sama dapat diberitahukan lebih dari sekali. Oleh karena itu, implementasi endpoint harus dilakukan secara idempoten.

Fallback — Jika terjadi ketidaktersediaan layanan webhook, disarankan untuk memiliki metode fallback agar Anda dapat terus mengambil status transaksi dalam waktu respons yang telah ditetapkan. Kueri endpoint dijelaskan pada bagian API Reference dari dokumentasi ini.

Terakhir diperbarui pada