Membangun Pendengar Webhook Didit dengan Fastify & PostgreSQL (ID)

Integrasi Webhook yang AmanMenerapkan verifikasi tanda tangan HMAC-SHA256 sangat penting untuk memastikan keaslian dan integritas muatan webhook Didit, melindungi aplikasi Anda dari permintaan palsu dan menjaga keamanan data.

Pemrosesan Data Real-timeManfaatkan webhook untuk menerima notifikasi instan tentang perubahan status sesi verifikasi identitas, memungkinkan aplikasi Anda bereaksi segera dan mengotomatiskan orientasi pengguna atau alur kerja manajemen risiko.

Penyimpanan Data yang SkalabelManfaatkan PostgreSQL untuk menyimpan dan mengelola data webhook secara efisien, memungkinkan kueri, audit, dan integrasi yang kuat dengan sistem manajemen pengguna Anda yang ada, memastikan persistensi dan keandalan data.

Keuntungan Modular DiditPlatform identitas modular Didit dan sistem webhook yang komprehensif menyederhanakan integrasi, menyediakan API yang bersih dan aliran data real-time bagi pengembang untuk membangun solusi KYC berbasis AI yang fleksibel dengan KYC Inti Gratis dan tanpa biaya pengaturan.

Memahami Webhook Didit dan Pentingnya

Dalam dunia verifikasi identitas, umpan balik real-time adalah yang terpenting. Baik Anda mengintegrasikan pengguna baru, mencegah penipuan, atau memastikan kepatuhan, mengetahui status sesi verifikasi saat itu terjadi sangatlah penting. Di sinilah webhook berperan. Webhook Didit menyediakan cara otomatis untuk menerima notifikasi tentang peristiwa yang terjadi dalam alur kerja verifikasi identitas Anda, seperti sesi selesai, gagal, atau memerlukan tindakan lebih lanjut.

Alih-alih terus-menerus melakukan polling API Didit untuk pembaruan, yang bisa tidak efisien dan menyebabkan penundaan, webhook mendorong data langsung ke titik akhir yang Anda konfigurasi. Arsitektur berbasis peristiwa ini memastikan aplikasi Anda selalu memiliki informasi terbaru, memungkinkan pemrosesan segera dan pengalaman pengguna yang lebih lancar. Misalnya, setelah pengguna berhasil menyelesaikan Verifikasi ID Didit dan pemeriksaan Pasif & Liveness Aktif, webhook dapat memicu langkah selanjutnya dalam alur orientasi Anda secara instan.

Didit menawarkan versi webhook yang dapat dikonfigurasi, dengan v3 menjadi standar yang direkomendasikan untuk struktur muatan yang komprehensif. Anda dapat mengatur URL webhook, versi, dan bahkan menentukan kebijakan retensi data langsung melalui Didit Business Console atau melalui API, memberi Anda kontrol penuh atas aliran data dan kewajiban kepatuhan Anda.

Menyiapkan Pendengar Webhook Fastify Anda

Fastify adalah kerangka kerja web yang cepat dan beroverhead rendah untuk Node.js, menjadikannya pilihan yang sangat baik untuk membangun pendengar webhook yang berkinerja tinggi. Berikut cara memulainya:

1. Pengaturan Proyek dan Dependensi

Pertama, inisialisasi proyek Node.js Anda dan instal paket yang diperlukan:

mkdir didit-webhook-listener
cd didit-webhook-listener
npm init -y
npm install fastify dotenv pg crypto

Buat file .env untuk menyimpan kunci rahasia webhook Didit dan detail koneksi PostgreSQL Anda:

DIDIT_WEBHOOK_SECRET=your_didit_webhook_secret_key
DATABASE_URL=postgresql://user:password@host:port/database

Anda dapat mengambil DIDIT_WEBHOOK_SECRET Anda dari Didit Business Console di bawah Pengaturan Aplikasi atau melalui titik akhir GET /v3/webhook/ Didit API.

2. Konfigurasi Server Fastify

Buat file app.js. Fastify memerlukan badan mentah untuk verifikasi tanda tangan, jadi kami akan mengonfigurasinya agar tidak mengurai JSON secara otomatis untuk rute webhook kami.

require('dotenv').config();
const fastify = require('fastify')({ logger: true });
const crypto = require('crypto');
const { Client } = require('pg');

const DIDIT_WEBHOOK_SECRET = process.env.DIDIT_WEBHOOK_SECRET;
const DATABASE_URL = process.env.DATABASE_URL;

const pgClient = new Client({ connectionString: DATABASE_URL });

// Daftarkan parser konten untuk 'application/json' yang membiarkan badan mentah untuk rute tertentu
fastify.addContentTypeParser('application/json', { parseAs: 'buffer' }, function (req, body, done) {
  if (req.raw.url === '/webhooks/didit') {
    done(null, body); // Biarkan mentah untuk titik akhir webhook
  } else {
    try {
      const json = JSON.parse(body.toString());
      done(null, json);
    } catch (error) {
      error.statusCode = 400;
      done(error, undefined);
    }
  }
});

fastify.post('/webhooks/didit', async (request, reply) => {
  const signature = request.headers['x-signature'];
  const timestamp = request.headers['x-timestamp'];
  const rawBody = request.body;

  if (!signature || !timestamp || !rawBody) {
    reply.code(400).send({ message: 'Missing signature, timestamp, or body' });
    return;
  }

  // 1. Verifikasi tanda tangan HMAC-SHA256
  const expectedSignature = crypto
    .createHmac('sha256', DIDIT_WEBHOOK_SECRET)
    .update(`${timestamp}.${rawBody.toString()}`)
    .digest('hex');

  if (expectedSignature !== signature) {
    reply.code(403).send({ message: 'Invalid signature' });
    return;
  }

  // 2. Validasi stempel waktu (misalnya, dalam 5 menit untuk mencegah serangan replay)
  const fiveMinutesAgo = Date.now() - (5 * 60 * 1000);
  if (parseInt(timestamp) < fiveMinutesAgo) {
    reply.code(403).send({ message: 'Timestamp too old' });
    return;
  }

  // 3. Urai badan JSON setelah verifikasi
  let payload;
  try {
    payload = JSON.parse(rawBody.toString());
  } catch (error) {
    reply.code(400).send({ message: 'Invalid JSON payload' });
    return;
  }

  fastify.log.info('Received Didit webhook:', payload);

  // 4. Proses muatan webhook (misalnya, simpan di DB, perbarui status pengguna)
  try {
    await pgClient.query(
      'INSERT INTO webhooks (event_id, event_type, payload, received_at) VALUES ($1, $2, $3, NOW())',
      [payload.id, payload.event, JSON.stringify(payload)]
    );
    // Contoh: Perbarui status pengguna berdasarkan payload.status
    // await pgClient.query(
    //   'UPDATE users SET verification_status = $1 WHERE didit_session_id = $2',
    //   [payload.status, payload.session_id]
    // );
    reply.code(200).send({ message: 'Webhook received and processed' });
  } catch (dbError) {
    fastify.log.error('Database error:', dbError);
    reply.code(500).send({ message: 'Internal server error' });
  }
});

const start = async () => {
  try {
    await pgClient.connect();
    fastify.log.info('Connected to PostgreSQL');
    await fastify.listen({ port: 3000, host: '0.0.0.0' });
  } catch (err) {
    fastify.log.error(err);
    process.exit(1);
  }
};

start();

Menyimpan Data Webhook di PostgreSQL

Mempertahankan data webhook sangat penting untuk audit, debugging, dan memastikan integritas data. PostgreSQL adalah basis data relasional yang kuat yang ideal untuk tugas ini.

1. Skema Basis Data

Pertama, buat tabel untuk menyimpan peristiwa webhook Anda. Skema ini menyediakan titik awal yang baik:

CREATE TABLE webhooks (
    id SERIAL PRIMARY KEY,
    event_id VARCHAR(255) UNIQUE NOT NULL, -- ID peristiwa unik Didit
    event_type VARCHAR(255) NOT NULL,
    payload JSONB NOT NULL, -- Simpan muatan JSON lengkap
    received_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

2. Mengintegrasikan dengan Fastify

Seperti yang ditunjukkan dalam contoh app.js, kami mengintegrasikan klien pg untuk terhubung ke basis data PostgreSQL Anda dan menyisipkan muatan webhook yang masuk. Kolom payload JSONB NOT NULL sangat cocok untuk menyimpan seluruh objek JSON, memungkinkan kueri yang fleksibel di kemudian hari tanpa perubahan skema yang telah ditentukan untuk setiap bidang baru yang mungkin diperkenalkan Didit.

Ingatlah untuk menangani potensi kesalahan basis data dengan baik. Contoh di atas menyertakan blok try-catch dasar untuk operasi basis data.

Mengamankan Titik Akhir Webhook Anda

Keamanan sangat penting saat berhadapan dengan data verifikasi identitas yang sensitif. Didit menggunakan tanda tangan HMAC-SHA256 untuk memastikan bahwa webhook yang masuk sah dan tidak dirusak.

1. Verifikasi Tanda Tangan HMAC

Setiap permintaan webhook Didit menyertakan dua header penting: X-Signature dan X-Timestamp. Header X-Signature berisi tanda tangan HMAC-SHA256 yang dibuat menggunakan rahasia webhook unik Anda dan badan permintaan mentah yang digabungkan dengan stempel waktu. Pendengar Anda harus:

1. Ambil DIDIT_WEBHOOK_SECRET Anda.
2. Ekstrak header X-Signature dan X-Timestamp.
3. Rekonstruksi muatan yang ditandatangani: `${timestamp}.${rawBody}`.
4. Hasilkan tanda tangan HMAC-SHA256 Anda sendiri menggunakan rahasia Anda dan muatan yang direkonstruksi.
5. Bandingkan tanda tangan yang Anda hasilkan dengan X-Signature dari permintaan. Jika tidak cocok, tolak permintaan.

Contoh Fastify yang disediakan menunjukkan proses ini dengan tepat, memastikan bahwa hanya webhook Didit yang autentik yang diproses.

2. Validasi Stempel Waktu

Header X-Timestamp sangat penting untuk mencegah serangan replay. Serangan replay terjadi ketika penyerang mencegat webhook yang sah dan mengirimkannya kembali di kemudian hari. Dengan memeriksa bahwa stempel waktu baru-baru ini (misalnya, dalam 5 menit dari waktu saat ini), Anda dapat mengurangi risiko ini. Cuplikan kode Fastify menyertakan pemeriksaan untuk memastikan stempel waktu tidak terlalu lama.

Bagaimana Didit Membantu

Platform Didit dirancang untuk membuat integrasi verifikasi identitas menjadi mulus dan aman. Arsitektur modular kami memungkinkan Anda untuk melakukan plug-and-play berbagai pemeriksaan identitas, mulai dari Verifikasi ID untuk analisis dokumen yang kuat hingga Verifikasi NFC untuk pemeriksaan ePaspor/eID keamanan tinggi, dan Penyaringan & Pemantauan AML untuk kepatuhan. Sistem webhook adalah komponen inti dari modularitas ini, menyediakan pembaruan real-time yang memungkinkan Anda mengatur alur kerja KYC yang kompleks tanpa polling terus-menerus.

Pendekatan berbasis AI Didit berarti sistem kami terus belajar dan beradaptasi, memberikan akurasi dan deteksi penipuan yang unggul. Dokumentasi API yang jelas dan mentalitas pengembang-pertama, dikombinasikan dengan fitur-fitur seperti KYC Inti Gratis dan tanpa biaya pengaturan, memudahkan untuk memulai. Webhook kami menyediakan data identitas terstruktur, memungkinkan aplikasi Anda bereaksi secara cerdas terhadap hasil verifikasi dan mengotomatiskan kepercayaan dalam skala besar, secara global. Baik Anda perlu memverifikasi usia menggunakan Estimasi Usia Didit atau memastikan pengguna adalah orang yang hidup dengan Liveness Pasif & Aktif, Didit menyediakan alat dan umpan balik real-time yang diperlukan untuk solusi identitas yang kuat.

Siap Memulai?

Siap melihat Didit beraksi? Dapatkan demo gratis hari ini.

Mulai verifikasi identitas secara gratis dengan tingkat gratis Didit.