Creación de un Oyente de Webhooks Didit con Fastify y PostgreSQL (ES)

Integración Segura de WebhooksImplementar la verificación de firmas HMAC-SHA256 es crucial para asegurar la autenticidad e integridad de las cargas útiles de los webhooks de Didit, protegiendo su aplicación de solicitudes falsificadas y manteniendo la seguridad de los datos.

Procesamiento de Datos en Tiempo RealUtilice webhooks para recibir notificaciones instantáneas sobre cambios en el estado de las sesiones de verificación de identidad, permitiendo que su aplicación reaccione inmediatamente y automatice los flujos de trabajo de incorporación de usuarios o gestión de riesgos.

Almacenamiento de Datos EscalableAproveche PostgreSQL para almacenar y gestionar eficientemente los datos de los webhooks, permitiendo consultas robustas, auditorías e integración con sus sistemas de gestión de usuarios existentes, asegurando la persistencia y fiabilidad de los datos.

La Ventaja Modular de DiditLa plataforma de identidad modular de Didit y su completo sistema de webhooks simplifican la integración, proporcionando a los desarrolladores APIs limpias y flujos de datos en tiempo real para construir soluciones KYC flexibles y nativas de IA con KYC Core Gratuito y sin tarifas de configuración.

Comprendiendo los Webhooks de Didit y su Importancia

En el mundo de la verificación de identidad, la retroalimentación en tiempo real es primordial. Ya sea que esté incorporando nuevos usuarios, previniendo fraudes o asegurando el cumplimiento, conocer el estado de una sesión de verificación a medida que ocurre es crítico. Aquí es donde entran en juego los webhooks. Los webhooks de Didit proporcionan una forma automatizada de recibir notificaciones sobre eventos que ocurren dentro de sus flujos de trabajo de verificación de identidad, como la finalización de una sesión, un fallo o la necesidad de una acción adicional.

En lugar de sondear constantemente la API de Didit en busca de actualizaciones, lo que puede ser ineficiente y provocar retrasos, los webhooks envían datos directamente a su punto final configurado. Esta arquitectura basada en eventos asegura que su aplicación siempre tenga la información más actualizada, lo que permite un procesamiento inmediato y una experiencia de usuario más fluida. Por ejemplo, una vez que un usuario completa con éxito la Verificación de ID de Didit y las comprobaciones de Prueba de Vida Pasiva y Activa, un webhook puede activar el siguiente paso en su flujo de incorporación al instante.

Didit ofrece versiones de webhook configurables, siendo la v3 el estándar recomendado por su estructura de carga útil completa. Puede establecer su URL de webhook, versión e incluso definir políticas de retención de datos directamente a través de la Consola de Negocios de Didit o mediante la API, lo que le da control total sobre su flujo de datos y sus obligaciones de cumplimiento.

Configuración de su Oyente de Webhooks Fastify

Fastify es un framework web rápido y de baja sobrecarga para Node.js, lo que lo convierte en una excelente opción para construir oyentes de webhooks de alto rendimiento. Así es como puede empezar:

1. Configuración del Proyecto y Dependencias

Primero, inicialice su proyecto Node.js e instale los paquetes necesarios:

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

Cree un archivo .env para almacenar su clave secreta de webhook de Didit y los detalles de conexión de PostgreSQL:

DIDIT_WEBHOOK_SECRET=su_clave_secreta_de_webhook_didit
DATABASE_URL=postgresql://usuario:contraseña@host:puerto/base_de_datos

Puede recuperar su DIDIT_WEBHOOK_SECRET desde la Consola de Negocios de Didit en Configuración de la Aplicación o a través del endpoint GET /v3/webhook/ de la API de Didit.

2. Configuración del Servidor Fastify

Cree un archivo app.js. Fastify necesita el cuerpo sin procesar para la verificación de la firma, por lo que lo configuraremos para que no analice JSON automáticamente para nuestra 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 analizador de contenido para 'application/json' que deja el cuerpo sin procesar para rutas específicas
fastify.addContentTypeParser('application/json', { parseAs: 'buffer' }, function (req, body, done) {
  if (req.raw.url === '/webhooks/didit') {
    done(null, body); // Dejar sin procesar para el 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: 'Missing signature, timestamp, or body' });
    return;
  }

  // 1. Verificar firma 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. Validar marca de tiempo (ej. dentro de 5 minutos para prevenir ataques de repetición)
  const fiveMinutesAgo = Date.now() - (5 * 60 * 1000);
  if (parseInt(timestamp) < fiveMinutesAgo) {
    reply.code(403).send({ message: 'Timestamp too old' });
    return;
  }

  // 3. Analizar cuerpo JSON después de la verificación
  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. Procesar la carga útil del webhook (ej. almacenar en DB, actualizar estado del usuario)
  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)]
    );
    // Ejemplo: Actualizar el estado del usuario basándose 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 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();

Almacenamiento de Datos de Webhook en PostgreSQL

La persistencia de los datos de los webhooks es crucial para la auditoría, la depuración y la garantía de la integridad de los datos. PostgreSQL es una base de datos relacional robusta ideal para esta tarea.

1. Esquema de la Base de Datos

Primero, cree una tabla para almacenar sus eventos de webhook. Este esquema proporciona un buen punto de partida:

CREATE TABLE webhooks (
    id SERIAL PRIMARY KEY,
    event_id VARCHAR(255) UNIQUE NOT NULL, -- ID único de evento de Didit
    event_type VARCHAR(255) NOT NULL,
    payload JSONB NOT NULL, -- Almacenar la carga útil JSON completa
    received_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

2. Integración con Fastify

Como se muestra en el ejemplo de app.js, integramos el cliente pg para conectarnos a su base de datos PostgreSQL e insertar la carga útil del webhook entrante. La columna payload JSONB NOT NULL es perfecta para almacenar todo el objeto JSON, permitiendo consultas flexibles más tarde sin cambios de esquema predefinidos para cada nuevo campo que Didit pueda introducir.

Recuerde manejar los posibles errores de la base de datos de manera elegante. El ejemplo anterior incluye un bloque básico try-catch para las operaciones de la base de datos.

Asegurando su Punto Final de Webhook

La seguridad es primordial cuando se trata de datos sensibles de verificación de identidad. Didit emplea firmas HMAC-SHA256 para asegurar que los webhooks entrantes sean legítimos y no hayan sido alterados.

1. Verificación de Firma HMAC

Cada solicitud de webhook de Didit incluye dos encabezados cruciales: X-Signature y X-Timestamp. El encabezado X-Signature contiene una firma HMAC-SHA256 generada utilizando su secreto de webhook único y el cuerpo de la solicitud sin procesar concatenado con la marca de tiempo. Su oyente debe:

1. Recuperar su DIDIT_WEBHOOK_SECRET.
2. Extraer los encabezados X-Signature y X-Timestamp.
3. Reconstruir la carga útil firmada: `${timestamp}.${rawBody}`.
4. Generar su propia firma HMAC-SHA256 utilizando su secreto y la carga útil reconstruida.
5. Comparar su firma generada con la X-Signature de la solicitud. Si no coinciden, rechace la solicitud.

El ejemplo de Fastify proporcionado demuestra este proceso exacto, asegurando que solo se procesen los webhooks auténticos de Didit.

2. Validación de Marca de Tiempo

El encabezado X-Timestamp es vital para prevenir ataques de repetición. Un ataque de repetición ocurre cuando un atacante intercepta un webhook legítimo y lo reenvía más tarde. Al verificar que la marca de tiempo sea reciente (por ejemplo, dentro de los 5 minutos de la hora actual), puede mitigar este riesgo. El fragmento de código de Fastify incluye una verificación para asegurar que la marca de tiempo no sea demasiado antigua.

Cómo Ayuda Didit

La plataforma de Didit está diseñada para hacer que la integración de la verificación de identidad sea fluida y segura. Nuestra arquitectura modular le permite conectar y usar varias comprobaciones de identidad, desde la verificación de ID para un análisis robusto de documentos hasta la verificación NFC para comprobaciones de alta seguridad de pasaportes/ID electrónicos, y el cribado y monitoreo AML para el cumplimiento. El sistema de webhooks es un componente central de esta modularidad, proporcionando actualizaciones en tiempo real que le permiten orquestar complejos flujos de trabajo KYC sin sondeos constantes.

El enfoque nativo de IA de Didit significa que nuestros sistemas están constantemente aprendiendo y adaptándose, proporcionando una precisión superior y detección de fraude. La clara documentación de la API y la mentalidad centrada en el desarrollador, combinadas con características como KYC Core gratuito y sin tarifas de configuración, facilitan el inicio. Nuestros webhooks proporcionan datos de identidad estructurados, permitiendo que su aplicación reaccione inteligentemente a los resultados de la verificación y automatice la confianza a escala, globalmente. Ya sea que necesite verificar la edad utilizando la Estimación de Edad de Didit o asegurarse de que un usuario sea una persona viva con la Prueba de Vida Pasiva y Activa, Didit proporciona las herramientas y la retroalimentación en tiempo real necesarias para una solución de identidad robusta.

¿Listo para Empezar?

¿Listo para ver Didit en acción? Obtenga una demostración gratuita hoy.

Empiece a verificar identidades de forma gratuita con el nivel gratuito de Didit.