Creant un Receptor de Webhooks Didit amb Fastify i PostgreSQL (CA)

Integració Segura de WebhooksImplementar la verificació de la signatura HMAC-SHA256 és crucial per garantir l'autenticitat i la integritat de les càrregues útils dels webhooks de Didit, protegint la vostra aplicació de sol·licituds falsificades i mantenint la seguretat de les dades.

Processament de Dades en Temps RealUtilitzeu webhooks per rebre notificacions instantànies sobre canvis d'estat de les sessions de verificació d'identitat, permetent que la vostra aplicació reaccioni immediatament i automatitzi els fluxos de treball d'incorporació d'usuaris o de gestió de riscos.

Emmagatzematge de Dades EscalableAprofiteu PostgreSQL per emmagatzemar i gestionar de manera eficient les dades dels webhooks, permetent consultes robustes, auditories i la integració amb els vostres sistemes de gestió d'usuaris existents, garantint la persistència i fiabilitat de les dades.

L'Avantatge Modular de DiditLa plataforma d'identitat modular de Didit i el seu sistema integral de webhooks simplifiquen la integració, proporcionant als desenvolupadors APIs netes i fluxos de dades en temps real per construir solucions KYC flexibles i natives d'IA amb KYC Core Gratuït i sense costos d'instal·lació.

Comprenent els Webhooks de Didit i la seva Importància

En el món de la verificació d'identitat, la retroalimentació en temps real és primordial. Tant si esteu incorporant nous usuaris, prevenint el frau o garantint el compliment, conèixer l'estat d'una sessió de verificació a mesura que succeeix és fonamental. Aquí és on entren els webhooks. Els webhooks de Didit proporcionen una manera automatitzada de rebre notificacions sobre esdeveniments que es produeixen dins dels vostres fluxos de treball de verificació d'identitat, com ara una sessió que es completa, falla o requereix una acció addicional.

En lloc de consultar constantment l'API de Didit per obtenir actualitzacions, cosa que pot ser ineficient i provocar retards, els webhooks envien dades directament al vostre punt final configurat. Aquesta arquitectura basada en esdeveniments garanteix que la vostra aplicació sempre tingui la informació més actualitzada, permetent un processament immediat i una experiència d'usuari més fluida. Per exemple, un cop un usuari completa amb èxit la verificació d'identitat de Didit i les comprovacions de vida passiva i activa, un webhook pot activar el següent pas del vostre flux d'incorporació a l'instant.

Didit ofereix versions de webhook configurables, sent la v3 l'estàndard recomanat per la seva estructura de càrrega útil completa. Podeu configurar la vostra URL de webhook, la versió i fins i tot definir polítiques de retenció de dades directament a través de la Consola de Negocis de Didit o mitjançant l'API, donant-vos un control total sobre el vostre flux de dades i les obligacions de compliment.

Configurant el vostre Receptor de Webhooks Fastify

Fastify és un marc web ràpid i de baix consum per a Node.js, cosa que el converteix en una excel·lent opció per construir receptors de webhooks d'alt rendiment. Aquí us expliquem com començar:

1. Configuració del Projecte i Dependències

Primer, inicialitzeu el vostre projecte Node.js i instal·leu els paquets necessaris:

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

Creeu un fitxer .env per emmagatzemar la clau secreta del webhook de Didit i els detalls de connexió de PostgreSQL:

DIDIT_WEBHOOK_SECRET=la_teva_clau_secreta_webhook_didit
DATABASE_URL=postgresql://usuari:contrasenya@host:port/base_de_dades

Podeu recuperar la vostra DIDIT_WEBHOOK_SECRET des de la Consola de Negocis de Didit a la secció Configuració de l'aplicació o mitjançant l'API de Didit a l'endpoint GET /v3/webhook/.

2. Configuració del Servidor Fastify

Creeu un fitxer app.js. Fastify necessita el cos en brut per a la verificació de la signatura, així que el configurarem perquè no processi JSON automàticament per a la nostra ruta de webhook.

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 });

// Registra un analitzador de contingut per a 'application/json' que deixa el cos en brut per a rutes específiques
fastify.addContentTypeParser('application/json', { parseAs: 'buffer' }, function (req, body, done) {
  if (req.raw.url === '/webhooks/didit') {
    done(null, body); // Deixa en brut per a l'endpoint del 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: 'Falta signatura, marca de temps o cos' });
    return;
  }

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

  if (expectedSignature !== signature) {
    reply.code(403).send({ message: 'Signatura invàlida' });
    return;
  }

  // 2. Valida la marca de temps (per exemple, dins de 5 minuts per prevenir atacs de reproducció)
  const fiveMinutesAgo = Date.now() - (5 * 60 * 1000);
  if (parseInt(timestamp) < fiveMinutesAgo) {
    reply.code(403).send({ message: 'Marca de temps massa antiga' });
    return;
  }

  // 3. Analitza el cos JSON després de la verificació
  let payload;
  try {
    payload = JSON.parse(rawBody.toString());
  } catch (error) {
    reply.code(400).send({ message: 'Càrrega útil JSON invàlida' });
    return;
  }

  fastify.log.info('Webhook de Didit rebut:', payload);

  // 4. Processa la càrrega útil del webhook (per exemple, emmagatzema a la base de dades, actualitza l'estat de l'usuari)
  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)]
    );
    // Exemple: Actualitza l'estat de l'usuari basant-se en 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 rebut i processat' });
  } catch (dbError) {
    fastify.log.error('Error de la base de dades:', dbError);
    reply.code(500).send({ message: 'Error intern del servidor' });
  }
});

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

start();

Emmagatzemant Dades de Webhooks a PostgreSQL

La persistència de les dades dels webhooks és crucial per a l'auditoria, la depuració i la garantia de la integritat de les dades. PostgreSQL és una base de dades relacional robusta ideal per a aquesta tasca.

1. Esquema de la Base de Dades

Primer, creeu una taula per emmagatzemar els vostres esdeveniments de webhook. Aquest esquema proporciona un bon punt de partida:

CREATE TABLE webhooks (
    id SERIAL PRIMARY KEY,
    event_id VARCHAR(255) UNIQUE NOT NULL, -- ID d'esdeveniment únic de Didit
    event_type VARCHAR(255) NOT NULL,
    payload JSONB NOT NULL, -- Emmagatzema la càrrega útil JSON completa
    received_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

2. Integració amb Fastify

Com es mostra a l'exemple de app.js, integrem el client pg per connectar-nos a la vostra base de dades PostgreSQL i inserir la càrrega útil del webhook entrant. La columna payload JSONB NOT NULL és perfecta per emmagatzemar tot l'objecte JSON, permetent consultes flexibles posteriorment sense canvis d'esquema predefinits per a cada nou camp que Didit pugui introduir.

Recordeu gestionar els possibles errors de la base de dades amb elegància. L'exemple anterior inclou un bloc bàsic try-catch per a les operacions de la base de dades.

Assegurant el vostre Endpoint de Webhook

La seguretat és primordial quan es tracta de dades sensibles de verificació d'identitat. Didit utilitza signatures HMAC-SHA256 per garantir que els webhooks entrants siguin legítims i no hagin estat alterats.

1. Verificació de la Signatura HMAC

Cada sol·licitud de webhook de Didit inclou dues capçaleres crucials: X-Signature i X-Timestamp. La capçalera X-Signature conté una signatura HMAC-SHA256 generada utilitzant la vostra clau secreta de webhook única i el cos de la sol·licitud en brut concatenat amb la marca de temps. El vostre receptor ha de:

1. Recuperar la vostra DIDIT_WEBHOOK_SECRET.
2. Extreure les capçaleres X-Signature i X-Timestamp.
3. Reconstruir la càrrega útil signada: `${timestamp}.${rawBody}`.
4. Generar la vostra pròpia signatura HMAC-SHA256 utilitzant la vostra clau secreta i la càrrega útil reconstruïda.
5. Comparar la vostra signatura generada amb la X-Signature de la sol·licitud. Si no coincideixen, rebutgeu la sol·licitud.

L'exemple de Fastify proporcionat demostra aquest procés exacte, garantint que només es processin els webhooks autèntics de Didit.

2. Validació de la Marca de Temps

La capçalera X-Timestamp és vital per prevenir atacs de reproducció. Un atac de reproducció es produeix quan un atacant intercepta un webhook legítim i el reenvia més tard. En comprovar que la marca de temps és recent (per exemple, dins dels 5 minuts de l'hora actual), podeu mitigar aquest risc. El fragment de codi de Fastify inclou una comprovació per assegurar que la marca de temps no és massa antiga.

Com Ajuda Didit

La plataforma de Didit està dissenyada per fer que la integració de la verificació d'identitat sigui fluida i segura. La nostra arquitectura modular us permet connectar i reproduir diverses comprovacions d'identitat, des de la verificació d'identitat per a una anàlisi robusta de documents fins a la verificació NFC per a comprovacions d'alta seguretat d'ePassport/eID, i el cribratge i monitorització AML per al compliment. El sistema de webhooks és un component central d'aquesta modularitat, proporcionant actualitzacions en temps real que us permeten orquestrar fluxos de treball KYC complexos sense una consulta constant.

L'enfocament natiu d'IA de Didit significa que els nostres sistemes estan constantment aprenent i adaptant-se, proporcionant una precisió superior i detecció de frau. La clara documentació de l'API i la mentalitat de desenvolupador, combinades amb funcions com KYC Core Gratuït i sense costos d'instal·lació, faciliten l'inici. Els nostres webhooks proporcionen dades d'identitat estructurades, permetent que la vostra aplicació reaccioni de manera intel·ligent als resultats de la verificació i automatitzi la confiança a escala, globalment. Tant si necessiteu verificar l'edat mitjançant l'estimació d'edat de Didit com si voleu assegurar-vos que un usuari és una persona viva amb la vida passiva i activa, Didit proporciona les eines i la retroalimentació en temps real necessàries per a una solució d'identitat robusta.

Preparat per Començar?

Preparat per veure Didit en acció? Obteniu una demostració gratuïta avui mateix.

Comenceu a verificar identitats de forma gratuïta amb el nivell gratuït de Didit.