Créer un écouteur de webhook Didit avec Fastify et PostgreSQL (FR)

Intégration sécurisée des webhooksL'implémentation de la vérification de signature HMAC-SHA256 est cruciale pour garantir l'authenticité et l'intégrité des charges utiles des webhooks Didit, protégeant votre application contre les requêtes falsifiées et maintenant la sécurité des données.

Traitement des données en temps réelUtilisez les webhooks pour recevoir des notifications instantanées sur les changements de statut des sessions de vérification d'identité, permettant à votre application de réagir immédiatement et d'automatiser les flux d'intégration des utilisateurs ou de gestion des risques.

Stockage de données évolutifTirez parti de PostgreSQL pour stocker et gérer efficacement les données des webhooks, permettant des requêtes robustes, l'audit et l'intégration avec vos systèmes de gestion d'utilisateurs existants, assurant la persistance et la fiabilité des données.

L'avantage modulaire de DiditLa plateforme d'identité modulaire de Didit et son système de webhook complet simplifient l'intégration, offrant aux développeurs des API claires et des flux de données en temps réel pour construire des solutions KYC flexibles et natives de l'IA avec Free Core KYC et sans frais d'installation.

Comprendre les webhooks Didit et leur importance

Dans le monde de la vérification d'identité, le feedback en temps réel est primordial. Que vous intégriez de nouveaux utilisateurs, préveniez la fraude ou assuriez la conformité, connaître le statut d'une session de vérification au moment où elle se produit est essentiel. C'est là qu'interviennent les webhooks. Les webhooks de Didit offrent un moyen automatisé de recevoir des notifications sur les événements survenant dans vos flux de travail de vérification d'identité, tels qu'une session terminée, échouée ou nécessitant une action supplémentaire.

Au lieu d'interroger constamment l'API Didit pour des mises à jour, ce qui peut être inefficace et entraîner des retards, les webhooks transmettent les données directement à votre endpoint configuré. Cette architecture événementielle garantit que votre application dispose toujours des informations les plus récentes, permettant un traitement immédiat et une expérience utilisateur plus fluide. Par exemple, une fois qu'un utilisateur a réussi la vérification d'identité de Didit et les contrôles de vivacité passive et active, un webhook peut déclencher instantanément l'étape suivante de votre flux d'intégration.

Didit propose des versions de webhook configurables, la v3 étant la norme recommandée pour sa structure de charge utile complète. Vous pouvez définir votre URL de webhook, sa version et même définir des politiques de rétention des données directement via la console métier Didit ou via l'API, vous donnant un contrôle total sur votre flux de données et vos obligations de conformité.

Configuration de votre écouteur de webhook Fastify

Fastify est un framework web rapide et léger pour Node.js, ce qui en fait un excellent choix pour construire des écouteurs de webhook performants. Voici comment commencer :

1. Configuration du projet et dépendances

Tout d'abord, initialisez votre projet Node.js et installez les packages nécessaires :

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

Créez un fichier .env pour stocker votre clé secrète de webhook Didit et les détails de connexion PostgreSQL :

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

Vous pouvez récupérer votre DIDIT_WEBHOOK_SECRET depuis la console métier Didit sous Paramètres de l'application ou via l'endpoint GET /v3/webhook/ de l'API Didit.

2. Configuration du serveur Fastify

Créez un fichier app.js. Fastify a besoin du corps brut pour la vérification de la signature, nous allons donc le configurer pour ne pas analyser automatiquement le JSON pour notre route 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 });

// Enregistre un analyseur de contenu pour 'application/json' qui laisse le corps brut pour des routes spécifiques
fastify.addContentTypeParser('application/json', { parseAs: 'buffer' }, function (req, body, done) {
  if (req.raw.url === '/webhooks/didit') {
    done(null, body); // Laisser brut pour l'endpoint du 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: 'Signature, horodatage ou corps manquant' });
    return;
  }

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

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

  // 2. Valider l'horodatage (par exemple, dans les 5 minutes pour prévenir les attaques par rejeu)
  const fiveMinutesAgo = Date.now() - (5 * 60 * 1000);
  if (parseInt(timestamp) < fiveMinutesAgo) {
    reply.code(403).send({ message: 'Horodatage trop ancien' });
    return;
  }

  // 3. Analyser le corps JSON après vérification
  let payload;
  try {
    payload = JSON.parse(rawBody.toString());
  } catch (error) {
    reply.code(400).send({ message: 'Charge utile JSON invalide' });
    return;
  }

  fastify.log.info('Webhook Didit reçu :', payload);

  // 4. Traiter la charge utile du webhook (par exemple, stocker dans la base de données, mettre à jour le statut de l'utilisateur)
  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 : Mettre à jour le statut de l'utilisateur en fonction de 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 reçu et traité' });
  } catch (dbError) {
    fastify.log.error('Erreur de base de données :', dbError);
    reply.code(500).send({ message: 'Erreur interne du serveur' });
  }
});

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

start();

Stockage des données de webhook dans PostgreSQL

La persistance des données de webhook est cruciale pour l'audit, le débogage et la garantie de l'intégrité des données. PostgreSQL est une base de données relationnelle robuste idéale pour cette tâche.

1. Schéma de la base de données

Tout d'abord, créez une table pour stocker vos événements de webhook. Ce schéma constitue un bon point de départ :

CREATE TABLE webhooks (
    id SERIAL PRIMARY KEY,
    event_id VARCHAR(255) UNIQUE NOT NULL, -- ID d'événement unique de Didit
    event_type VARCHAR(255) NOT NULL,
    payload JSONB NOT NULL, -- Stocker la charge utile JSON complète
    received_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

2. Intégration avec Fastify

Comme indiqué dans l'exemple app.js, nous intégrons le client pg pour nous connecter à votre base de données PostgreSQL et insérer la charge utile du webhook entrant. La colonne payload JSONB NOT NULL est parfaite pour stocker l'objet JSON entier, permettant des requêtes flexibles ultérieurement sans modifications de schéma prédéfinies pour chaque nouveau champ que Didit pourrait introduire.

N'oubliez pas de gérer les erreurs potentielles de la base de données avec élégance. L'exemple ci-dessus inclut un bloc try-catch de base pour les opérations de base de données.

Sécurisation de votre endpoint de webhook

La sécurité est primordiale lorsqu'il s'agit de données sensibles de vérification d'identité. Didit utilise des signatures HMAC-SHA256 pour garantir que les webhooks entrants sont légitimes et non altérés.

1. Vérification de la signature HMAC

Chaque requête de webhook Didit inclut deux en-têtes cruciaux : X-Signature et X-Timestamp. L'en-tête X-Signature contient une signature HMAC-SHA256 générée à l'aide de votre secret de webhook unique et du corps de la requête brute concaténé avec l'horodatage. Votre écouteur doit :

1. Récupérer votre DIDIT_WEBHOOK_SECRET.
2. Extraire les en-têtes X-Signature et X-Timestamp.
3. Reconstruire la charge utile signée : `${timestamp}.${rawBody}`.
4. Générer votre propre signature HMAC-SHA256 à l'aide de votre secret et de la charge utile reconstruite.
5. Comparer votre signature générée avec le X-Signature de la requête. S'ils ne correspondent pas, rejetez la requête.

L'exemple Fastify fourni démontre ce processus exact, garantissant que seuls les webhooks Didit authentiques sont traités.

2. Validation de l'horodatage

L'en-tête X-Timestamp est vital pour prévenir les attaques par rejeu. Une attaque par rejeu se produit lorsqu'un attaquant intercepte un webhook légitime et le renvoie plus tard. En vérifiant que l'horodatage est récent (par exemple, dans les 5 minutes suivant l'heure actuelle), vous pouvez atténuer ce risque. L'extrait de code Fastify inclut une vérification pour s'assurer que l'horodatage n'est pas trop ancien.

Comment Didit aide

La plateforme de Didit est conçue pour rendre l'intégration de la vérification d'identité transparente et sécurisée. Notre architecture modulaire vous permet de brancher et de jouer diverses vérifications d'identité, de la vérification d'identité pour une analyse robuste des documents à la vérification NFC pour des contrôles d'ePassport/eID de haute sécurité, et au filtrage et à la surveillance AML pour la conformité. Le système de webhook est un composant essentiel de cette modularité, fournissant des mises à jour en temps réel qui vous permettent d'orchestrer des workflows KYC complexes sans sondage constant.

L'approche native de l'IA de Didit signifie que nos systèmes apprennent et s'adaptent constamment, offrant une précision supérieure et une détection de la fraude. La documentation API claire et la mentalité axée sur les développeurs, combinées à des fonctionnalités telles que Free Core KYC et l'absence de frais d'installation, facilitent le démarrage. Nos webhooks fournissent des données d'identité structurées, permettant à votre application de réagir intelligemment aux résultats de vérification et d'automatiser la confiance à grande échelle, à l'échelle mondiale. Que vous ayez besoin de vérifier l'âge à l'aide de l'estimation de l'âge de Didit ou de vous assurer qu'un utilisateur est une personne vivante avec la vivacité passive et active, Didit fournit les outils et le feedback en temps réel nécessaires à une solution d'identité robuste.

Prêt à commencer ?

Prêt à voir Didit en action ? Obtenez une démo gratuite dès aujourd'hui.

Commencez à vérifier les identités gratuitement avec le niveau gratuit de Didit.