Referensi API Webhook FACEIO

Terima notifikasi HTTPS POST saat pengguna melakukan pendaftaran, autentikasi dengan FACEIO, atau menghapus Facial ID. Gunakan webhook untuk menyinkronkan backend dengan event autentikasi wajah tanpa hanya bergantung pada status frontend.

BUKA FACEIO Console

Buat atau pilih aplikasi di FACEIO Console, daftarkan endpoint HTTPS, lalu ambil token webhook yang ditetapkan untuk aplikasi.

Ringkasan Webhook FACEIO

Pengiriman event sisi server untuk pendaftaran, autentikasi, dan penghapusan Facial ID

Webhook FACEIO memberi tahu backend setelah pendaftaran baru, autentikasi wajah yang berhasil, atau penghapusan Facial ID. Gunakan event sisi server ini untuk mencocokkan catatan akun Anda dengan aktivitas FACEIO.

Saat event dipicu, FACEIO mengirimkan permintaan HTTPS POST ke URL endpoint webhook yang dikonfigurasikan untuk aplikasi Anda. Payload JSON mengidentifikasi Facial ID unik, ID publik aplikasi, nama event, alamat IP klien, timestamp, payload terkait jika tersedia, serta detail pendaftaran seperti perkiraan usia dan gender.

Gunakan event webhook untuk memperbarui catatan backend, membuat jejak audit, atau memicu alur sisi server Anda sendiri. Validasi setiap webhook yang masuk sebelum memproses payload dan ikuti praktik terbaik keamanan FACEIO.

Pembaruan Real-Time

Terima notifikasi event saat pengguna melakukan pendaftaran, autentikasi, atau menyelesaikan penghapusan Facial ID.

Sinkronisasi Backend

Perbarui catatan akun internal dari event sisi server yang tepercaya, bukan hanya mengandalkan callback browser.

Konfigurasikan Webhook FACEIO

Konfigurasikan endpoint webhook untuk setiap aplikasi FACEIO yang memerlukan pengiriman event ke backend. Endpoint harus menerima JSON melalui HTTPS dan memvalidasi WWW-Authenticate token, lalu mengembalikan respons berhasil dengan cepat.

Buka FACEIO Console

Masuk ke akun Anda di FACEIO Console ↗.

Buka Application Manager

Dari tampilan utama Console, buka Application Manager ↗.

Pilih Aplikasi Target

Pilih aplikasi FACEIO yang akan mengirim notifikasi pendaftaran, autentikasi, dan penghapusan Facial ID.

Buka Tab Webhook

Buka WEBHOOKS tab dari tampilan Application Manager.

Tambahkan URL Endpoint

Masukkan URL endpoint webhook yang akan menerima event FACEIO, lalu simpan pengaturan aplikasi.

✓

Mulai Menerima Event

Setelah event dipicu, FACEIO akan mengirim permintaan HTTPS POST ke URL webhook dengan payload JSON yang dijelaskan di bawah.

Detail Permintaan HTTP

URL endpoint webhook harus menangani permintaan HTTPS masuk dari FACEIO setiap kali event dipicu. Format permintaan dirangkum di bawah.

Metode HTTP	POST
Tipe Konten	`application/json`
Payload POST	Objek JSON. Lihat bagian di bawah untuk kolom body yang diharapkan.
Batas Waktu	6 Detik Server HTTP harus menerima permintaan POST dalam waktu kurang dari 6 detik. Setelah batas ini, FACEIO otomatis membatalkan koneksi.
Header WWW-Authenticate Header HTTP `WWW-Authenticate` selalu disertakan pada setiap permintaan POST yang dimulai FACEIO.	Khusus untuk setiap aplikasi FACEIO *Verifikasi keaslian permintaan dengan memeriksa nilai token Bearer* yang tertanam di header HTTP `WWW-Authenticate`. Nilai ini harus sama dengan kunci token yang ditetapkan untuk aplikasi Anda.** Ambil kunci token ini dari Application Manager di FACEIO Console ↗.

Praktik Terbaik Keamanan

Selalu verifikasi permintaan webhook yang masuk dengan membandingkan token header WWW-Authenticate dengan kunci token aplikasi Anda. Tolak ketidaksesuaian, proses event secara idempoten, dan baca praktik terbaik keamanan sebelum menggunakan event webhook dalam alur otorisasi produksi.

Isi Permintaan POST

Body setiap permintaan webhook FACEIO yang masuk adalah objek JSON. Gunakan kolom di bawah untuk mengidentifikasi event, mencocokkannya dengan aplikasi FACEIO, dan mencocokkannya dengan catatan akun Anda.

webhook-payload.json

{
  "eventName": "String - Nama event",
  "facialId": "String - Facial ID unik pengguna target",
  "appId": "String - Public ID aplikasi",
  "clientIp": "String - Alamat IP publik",
  "payload": "Blob - Data yang dikaitkan dengan pengguna, jika ada (tersedia mulai paket Business)",
  "details": {
    "timestamp": "String opsional - Timestamp event",
    "gender": "String opsional - Gender pengguna terdaftar",
    "age": "String opsional - Perkiraan usia pengguna terdaftar"
  }
}

Gunakan nilai token dari header HTTP WWW-Authenticate yang tersedia di FACEIO Console ↗ untuk memverifikasi keaslian permintaan.

`eventName`	adalah nama event yang memicu permintaan ini.
`facialId`	adalah Facial ID unik pengguna yang sedang didaftarkan atau diautentikasi
`appId`	adalah ID publik aplikasi yang memicu permintaan ini. Anda dapat menemukan ID publik setiap aplikasi di FACEIO Console ↗.
`clientIp`	adalah alamat IP publik sesi browser yang menginisialisasi `fio.js`. Baca praktik terbaik privasi sebelum menyimpan atau mempertahankan data IP klien.
`payload`	adalah data yang telah Anda kaitkan dengan pengguna ini, jika ada, selama pendaftaran. Jaga payload tetap minimal dan jangan simpan rahasia atau data pribadi yang tidak diperlukan. Data yang sama juga akan diteruskan ke frontend JavaScript Anda pada autentikasi mendatang untuk pengguna yang sama. Kolom `payload` disertakan dalam pemanggilan webhook hanya jika aplikasi Anda menggunakan Business Plan atau paket yang lebih tinggi. Lihat halaman harga untuk informasi tambahan. Kolom ini tidak disertakan dalam event penghapusan Facial ID `DELETION`.

Kolom Opsional (Hanya Pendaftaran)

Kolom berikut dalam body JSON disertakan untuk event pendaftaran pengguna baru:

`timestamp`	adalah tanggal operasi (UTC) dalam format YYYY-MM-DD.
`gender`	Gender pengguna yang didaftarkan: male atau female.
`age`	Perkiraan usia pengguna yang didaftarkan.

Event

Setiap permintaan HTTPS POST yang dikirim ke endpoint webhook dipicu oleh salah satu event FACEIO berikut. Kolom eventName pada payload JSON POST berisi kunci terkait.

Nama Event	Deskripsi
`ENROLL`	Dipicu setelah pengguna menyelesaikan pendaftaran.
`AUTH`	Dipicu setelah pengguna menyelesaikan autentikasi.
`DELETION`	Dipicu setelah penghapusan Facial ID selesai.

Tips Implementasi

Pastikan endpoint webhook merespons dalam 6 detik untuk menghindari timeout.
Selalu validasi WWW-Authenticate token header demi keamanan.
Tangani event webhook secara asinkron dan idempoten agar aplikasi tidak terblokir.
Catat hanya metadata yang diperlukan untuk debugging, rekonsiliasi, dan audit.
Kembalikan kode status 200 OK untuk mengonfirmasi penerimaan webhook.
Gunakan REST API saat backend perlu memverifikasi atau merekonsiliasi status Facial ID setelah event.

Konfigurasikan Webhook untuk Backend Anda

Daftarkan URL webhook HTTPS di FACEIO Console, validasi token webhook di server, lalu proses event pendaftaran, autentikasi, dan penghapusan Facial ID di backend.

Baca Panduan Integrasi → Buka FACEIO Console

URL Webhook HTTPS

Validasi Token Webhook

Sinkronisasi Backend Berbasis Event