Mendapatkan hasil verifikasi dengan webhook
Didit tidak mengirim email saat status verifikasi berubah - siapkan webhook agar backend Anda mengetahuinya begitu itu terjadi, dan verifikasi signature-nya sebelum Anda mempercayainya.
Webhook adalah permintaan HTTP yang dikirim Didit ke URL Anda saat ada sesuatu yang berubah. Tambahkan destinasi di API & Webhooks, subscribe ke event yang Anda inginkan - tidak ada wildcard, daftarkan semuanya satu per satu - simpan signing secret-nya, dan verifikasi signature-nya sebelum Anda memproses apa pun.
Didit tidak mengirimkan email saat sesi berpindah ke In Review atau Declined. Untuk mengetahui persis kapan sebuah status berubah, tanpa harus me-refresh konsol, siapkan webhook - sebuah URL di server Anda yang secara otomatis dikirimi update oleh Didit.
Webhook adalah pola integrasi yang direkomendasikan. Melakukan polling ke endpoint keputusan tetap bisa jadi cadangan, tapi lebih lambat, membutuhkan lebih banyak permintaan, dan melewatkan event yang hanya pernah dikirim lewat webhook - perubahan data oleh reviewer, perubahan status transaksi, dan perubahan di level entity.
#Menyiapkannya
- Go to API & Webhooks
Di Business Console, buka aplikasi yang ingin Anda terima event-nya, lalu buka API & Webhooks.
- Add a destination
Beri label, URL HTTPS publik endpoint Anda, dan pilih event yang ingin Anda terima - minimal perubahan status sesi.
- Save the signing secret
Destinasi tersebut menampilkan sebuah secret satu kali saja. Simpan itu - server Anda menggunakannya untuk memastikan sebuah permintaan benar-benar berasal dari Didit dan bukan dari peniru. Langkah verifikasi lengkap: Verifikasi signature.
- Test it
Gunakan Try Webhook di halaman yang sama untuk mengirim event uji coba yang terbentuk lengkap - skenario approved, declined, in review, KYB, entity, dan transaction - ke endpoint Anda. Anda bisa memvalidasi integrasi Anda dengan cara ini tanpa perlu menjalankan verifikasi sungguhan.
- Add destination mendaftarkan URL tempat Didit mengirim hasilnya.
- Verifikasi setiap pengiriman terhadap signing secret ini sebelum Anda mempercayainya.
- Pilih event mana saja yang diterima oleh sebuah destinasi.
- Test Webhook mengirim payload contoh sehingga Anda bisa memastikan endpoint Anda menerimanya.
#Event yang bisa Anda subscribe
Tidak ada wildcard - daftarkan setiap keluarga event yang Anda inginkan. Menyebarkannya ke beberapa destinasi juga tidak masalah dan sering kali lebih rapi.
| Event | Terpicu saat |
|---|---|
status.updated | Status sesi KYC atau KYB berubah. Yang hampir pasti Anda inginkan |
data.updated | Data verifikasi diedit setelah dibuat - misalnya reviewer mengoreksi sebuah field |
user.status.updated | Pengguna konsolidasi berpindah antara ACTIVE, FLAGGED dan BLOCKED |
user.data.updated | Profil, counter, atau identifier pengguna konsolidasi berubah |
business.status.updated | Status bisnis konsolidasi berubah |
business.data.updated | Data bisnis konsolidasi berubah |
transaction.created | Sebuah transaksi dibuat dan verdict awalnya sudah siap |
transaction.status.updated | Status sebuah transaksi berubah setelahnya |
travel_rule.status.updated | Status pertukaran Travel Rule berubah |
Tidak ada session.status.updated atau kyc.completed. Jika Anda men-subscribe
nama yang tidak ada di daftar ini, Anda tidak akan menerima apa pun - dan itu akan
terlihat persis seperti kegagalan pengiriman. Periksa dulu namanya.
#Yang seharusnya dilakukan endpoint Anda
- Verifikasi signature-nya sebelum apa pun. Lakukan HMAC pada body permintaan mentah - jangan pernah versi hasil serialize ulang dari JSON yang sudah di-parse, karena menyusunnya kembali menjadi string mengubah byte-nya dan signature-nya tidak akan cocok. Gunakan perbandingan constant-time.
- Kembalikan 2xx dengan cepat. Lakukan pekerjaan berat secara asinkron, setelah Anda merespons.
- Bersifat idempotent. Gunakan id event, atau kombinasi id sesi + status + jenis webhook sebagai kunci. Percobaan ulang dan duplikat bisa terjadi.
- Tangani setiap status yang Anda pedulikan, termasuk yang muncul lama setelah onboarding - sesi yang sudah approved bisa berpindah ke In Review kemudian lewat pemantauan AML berkelanjutan.
- Hanya HTTPS. Endpoint HTTP biasa tidak didukung.
#Percobaan ulang
Pada 5xx, 404, timeout, atau kegagalan koneksi, Didit mencoba ulang dua kali:
- Percobaan ulang pertama sekitar 1 menit setelah kegagalan awal
- Percobaan ulang kedua sekitar 4 menit setelah itu
Setelah itu pengirimannya dihentikan. Setiap percobaan dicatat terpisah di tab Deliveries milik destinasi tersebut, sehingga Anda bisa melihat persis apa yang terjadi alih-alih menebak-nebak.
Dua kali percobaan ulang dalam lima menit bukanlah antrean yang tahan lama. Jika endpoint Anda mati selama satu jam, event-event tersebut hilang. Lakukan rekonsiliasi saat startup dengan melakukan polling ke endpoint keputusan untuk sesi yang belum Anda miliki status terminalnya - webhook adalah jalur cepat, bukan satu-satunya jalur.
#Di belakang firewall atau WAF
Didit mengirim dari IP statis 18.203.201.92 dengan user agent DiditWebhook/2.0. Jika edge Anda memblokir klien yang tidak dikenal - seperti kebijakan default Cloudflare - izinkan IP tersebut untuk hostname penerima, atau pengiriman akan gagal sebelum sampai ke kode Anda.
#Belum punya backend?
Anda tetap bisa memantau hasil secara manual di bagian Verifications milik konsol sambil membangunnya, atau gunakan link verifikasi tanpa kode untuk sementara.
#Langkah berikutnya
- Ketika webhook tidak sampai: ketika webhook tidak pernah sampai
- Memahami arti setiap status begitu ia sampai: apa arti setiap status sesi
- Referensi teknis lengkap, termasuk contoh kode verifikasi signature: Webhooks