Webhook Events

Webhook memungkinkan aplikasi Anda untuk menerima notifikasi real-time secara asinkron dari server kami saat alur verifikasi pada client SDK telah diselesaikan oleh pengguna.

Cara Kerja Webhook

Berbeda dengan REST API di mana aplikasi Anda yang memanggil server kami, dengan Webhook:

1. Anda mendaftarkan Webhook URL tujuan melalui halaman Developer Console (Settings > Webhooks) di dashboard Anda.
2. Pengguna menyelesaikan proses verifikasi pada Web/Mobile SDK Anda.
3. Server kami mengirimkan HTTP POST request secara otomatis ke Webhook URL terdaftar Anda.

Struktur Payload Webhook (Universal Envelope)

Setiap callback webhook dibungkus dalam struktur payload metadata standar (universal envelope). Nilai di dalam field data akan menyesuaikan dengan flow yang dijalankan. Berikut adalah format payload JSON standar:

{
  "event": "session.completed",
  "session_id": "sess_56789",
  "status": "completed",
  "occurred_at": "2026-06-11T13:21:00Z",
  "data": {
    "flow": "ocr_only",
    "external_user_id": "user_unik_99",
    "ocr_result": {
      "nik": "3201010101900001",
      "name": "BUDI SANTOSO"
    }
  }
}

Event Types yang Didukung

Saat ini sistem mendukung tipe event berikut:

• session.completed : Dikirimkan saat alur verifikasi pada SDK session (seperti OCR atau Liveness) selesai dilakukan oleh pengguna.
• webhook.test : Dikirimkan ketika Anda menekan tombol "Test Webhook" di Developer Console dashboard Anda.

Verifikasi Tanda Tangan (Signature Verification)

Untuk memastikan request webhook benar-benar berasal dari server kami (dan tidak dipalsukan oleh pihak lain), setiap request menyertakan header signature X-OGI-Signature.

Signature ini dibuat dengan algoritma HMAC SHA-256 menggunakan payload mentah (raw request body) dan Webhook Secret Key Anda yang dapat disalin dari dashboard.

Contoh verifikasi signature di Node.js:

const crypto = require('crypto');
const signature = req.headers['x-ogi-signature'];
const expectedSignature = crypto
  .createHmac('sha256', process.env.WEBHOOK_SECRET)
  .update(JSON.stringify(req.body))
  .digest('hex');

if (signature === expectedSignature) {
  console.log('Webhook valid!');
} else {
  console.error('Signature verification failed.');
}