Didit Webhook-Listener mit Fastify & PostgreSQL aufbauen (DE)

Sichere Webhook-IntegrationDie Implementierung der HMAC-SHA256-Signaturprüfung ist entscheidend, um die Authentizität und Integrität von Didit-Webhook-Payloads zu gewährleisten, Ihre Anwendung vor gefälschten Anfragen zu schützen und die Datensicherheit zu wahren.

Echtzeit-DatenverarbeitungNutzen Sie Webhooks, um sofortige Benachrichtigungen über Statusänderungen von Identitätsverifizierungssitzungen zu erhalten, sodass Ihre Anwendung sofort reagieren und Benutzer-Onboarding- oder Risikomanagement-Workflows automatisieren kann.

Skalierbare DatenspeicherungNutzen Sie PostgreSQL, um Webhook-Daten effizient zu speichern und zu verwalten, was robuste Abfragen, Audits und die Integration in Ihre bestehenden Benutzerverwaltungssysteme ermöglicht und Datenpersistenz und Zuverlässigkeit gewährleistet.

Didits modularer VorteilDidits modulare Identitätsplattform und das umfassende Webhook-System vereinfachen die Integration und bieten Entwicklern saubere APIs und Echtzeit-Datenflüsse zum Aufbau flexibler, KI-nativer KYC-Lösungen mit kostenlosem Core KYC und ohne Einrichtungsgebühren.

Didit-Webhooks und ihre Bedeutung verstehen

In der Welt der Identitätsprüfung ist Echtzeit-Feedback von größter Bedeutung. Ob Sie neue Benutzer onboarden, Betrug verhindern oder die Einhaltung von Vorschriften sicherstellen, der Status einer Verifizierungssitzung in Echtzeit zu kennen, ist entscheidend. Hier kommen Webhooks ins Spiel. Didits Webhooks bieten eine automatisierte Möglichkeit, Benachrichtigungen über Ereignisse in Ihren Identitätsverifizierungs-Workflows zu erhalten, z. B. wenn eine Sitzung abgeschlossen, fehlgeschlagen ist oder weitere Maßnahmen erfordert.

Anstatt ständig die Didit-API nach Updates abzufragen, was ineffizient sein und zu Verzögerungen führen kann, senden Webhooks Daten direkt an Ihren konfigurierten Endpunkt. Diese ereignisgesteuerte Architektur stellt sicher, dass Ihre Anwendung immer die aktuellsten Informationen hat, was eine sofortige Verarbeitung und ein reibungsloseres Benutzererlebnis ermöglicht. Wenn ein Benutzer beispielsweise die Didit ID-Verifizierung und die passive & aktive Liveness-Prüfung erfolgreich abgeschlossen hat, kann ein Webhook den nächsten Schritt in Ihrem Onboarding-Flow sofort auslösen.

Didit bietet konfigurierbare Webhook-Versionen an, wobei v3 der empfohlene Standard für seine umfassende Payload-Struktur ist. Sie können Ihre Webhook-URL, Version und sogar Datenaufbewahrungsrichtlinien direkt über die Didit Business Console oder über die API festlegen, was Ihnen die volle Kontrolle über Ihren Datenfluss und Ihre Compliance-Verpflichtungen gibt.

Einrichten Ihres Fastify Webhook-Listeners

Fastify ist ein schnelles und ressourcenschonendes Web-Framework für Node.js, was es zu einer ausgezeichneten Wahl für den Aufbau performanter Webhook-Listener macht. So fangen Sie an:

1. Projekt-Setup und Abhängigkeiten

Initialisieren Sie zuerst Ihr Node.js-Projekt und installieren Sie die notwendigen Pakete:

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

Erstellen Sie eine .env-Datei, um Ihren Didit-Webhook-Geheimschlüssel und die PostgreSQL-Verbindungsinformationen zu speichern:

DIDIT_WEBHOOK_SECRET=ihr_didit_webhook_geheimschlüssel
DATABASE_URL=postgresql://benutzer:passwort@host:port/datenbank

Sie können Ihren DIDIT_WEBHOOK_SECRET aus der Didit Business Console unter App-Einstellungen oder über den GET /v3/webhook/-Endpunkt der Didit API abrufen.

2. Fastify Server-Konfiguration

Erstellen Sie eine app.js-Datei. Fastify benötigt den rohen Body für die Signaturprüfung, daher werden wir es so konfigurieren, dass es JSON für unsere Webhook-Route nicht automatisch parst.

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

// Registrieren Sie einen Content-Parser für 'application/json', der den Body für spezifische Routen roh lässt
fastify.addContentTypeParser('application/json', { parseAs: 'buffer' }, function (req, body, done) {
  if (req.raw.url === '/webhooks/didit') {
    done(null, body); // Roh lassen für Webhook-Endpunkt
  } 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: 'Fehlende Signatur, Zeitstempel oder Body' });
    return;
  }

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

  if (expectedSignature !== signature) {
    reply.code(403).send({ message: 'Ungültige Signatur' });
    return;
  }

  // 2. Zeitstempel validieren (z.B. innerhalb von 5 Minuten, um Replay-Angriffe zu verhindern)
  const fiveMinutesAgo = Date.now() - (5 * 60 * 1000);
  if (parseInt(timestamp) < fiveMinutesAgo) {
    reply.code(403).send({ message: 'Zeitstempel zu alt' });
    return;
  }

  // 3. JSON-Body nach der Überprüfung parsen
  let payload;
  try {
    payload = JSON.parse(rawBody.toString());
  } catch (error) {
    reply.code(400).send({ message: 'Ungültiger JSON-Payload' });
    return;
  }

  fastify.log.info('Didit-Webhook empfangen:', payload);

  // 4. Webhook-Payload verarbeiten (z.B. in DB speichern, Benutzerstatus aktualisieren)
  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)]
    );
    // Beispiel: Benutzerstatus basierend auf payload.status aktualisieren
    // 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 empfangen und verarbeitet' });
  } catch (dbError) {
    fastify.log.error('Datenbankfehler:', dbError);
    reply.code(500).send({ message: 'Interner Serverfehler' });
  }
});

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

start();

Webhook-Daten in PostgreSQL speichern

Das Speichern von Webhook-Daten ist entscheidend für Audits, Debugging und die Sicherstellung der Datenintegrität. PostgreSQL ist eine robuste relationale Datenbank, die sich ideal für diese Aufgabe eignet.

1. Datenbankschema

Erstellen Sie zunächst eine Tabelle, um Ihre Webhook-Ereignisse zu speichern. Dieses Schema bietet einen guten Ausgangspunkt:

CREATE TABLE webhooks (
    id SERIAL PRIMARY KEY,
    event_id VARCHAR(255) UNIQUE NOT NULL, -- Didits eindeutige Ereignis-ID
    event_type VARCHAR(255) NOT NULL,
    payload JSONB NOT NULL, -- Den vollständigen JSON-Payload speichern
    received_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

2. Integration mit Fastify

Wie im app.js-Beispiel gezeigt, integrieren wir den pg-Client, um eine Verbindung zu Ihrer PostgreSQL-Datenbank herzustellen und den eingehenden Webhook-Payload einzufügen. Die Spalte payload JSONB NOT NULL ist perfekt, um das gesamte JSON-Objekt zu speichern, was später flexible Abfragen ohne vordefinierte Schemaänderungen für jedes neue Feld, das Didit möglicherweise einführt, ermöglicht.

Denken Sie daran, potenzielle Datenbankfehler elegant zu behandeln. Das obige Beispiel enthält einen grundlegenden try-catch-Block für Datenbankoperationen.

Sichern Ihres Webhook-Endpunkts

Sicherheit ist von größter Bedeutung, wenn es um sensible Identitätsverifizierungsdaten geht. Didit verwendet HMAC-SHA256-Signaturen, um sicherzustellen, dass eingehende Webhooks legitim und unverändert sind.

1. HMAC-Signaturprüfung

Jede Didit-Webhook-Anfrage enthält zwei entscheidende Header: X-Signature und X-Timestamp. Der X-Signature-Header enthält eine HMAC-SHA256-Signatur, die mit Ihrem eindeutigen Webhook-Geheimnis und dem rohen Anfragetext, verkettet mit dem Zeitstempel, generiert wird. Ihr Listener muss:

1. Ihren DIDIT_WEBHOOK_SECRET abrufen.
2. Die Header X-Signature und X-Timestamp extrahieren.
3. Den signierten Payload rekonstruieren: `${timestamp}.${rawBody}`.
4. Eine eigene HMAC-SHA256-Signatur unter Verwendung Ihres Geheimnisses und des rekonstruierten Payloads generieren.
5. Ihre generierte Signatur mit der X-Signature aus der Anfrage vergleichen. Wenn sie nicht übereinstimmen, die Anfrage ablehnen.

Das bereitgestellte Fastify-Beispiel demonstriert genau diesen Prozess und stellt sicher, dass nur authentische Didit-Webhooks verarbeitet werden.

2. Zeitstempelvalidierung

Der X-Timestamp-Header ist entscheidend, um Replay-Angriffe zu verhindern. Ein Replay-Angriff tritt auf, wenn ein Angreifer einen legitimen Webhook abfängt und ihn später erneut sendet. Indem Sie überprüfen, ob der Zeitstempel aktuell ist (z. B. innerhalb von 5 Minuten nach der aktuellen Zeit), können Sie dieses Risiko mindern. Der Fastify-Code-Snippet enthält eine Überprüfung, um sicherzustellen, dass der Zeitstempel nicht zu alt ist.

Wie Didit hilft

Didits Plattform wurde entwickelt, um die Integration der Identitätsprüfung nahtlos und sicher zu gestalten. Unsere modulare Architektur ermöglicht es Ihnen, verschiedene Identitätsprüfungen "plug-and-play" zu verwenden, von der ID-Verifizierung für robuste Dokumentenanalysen über die NFC-Verifizierung für hochsichere ePassport-/eID-Prüfungen bis hin zum AML-Screening & Monitoring zur Einhaltung von Vorschriften. Das Webhook-System ist eine Kernkomponente dieser Modularität und liefert Echtzeit-Updates, die es Ihnen ermöglichen, komplexe KYC-Workflows ohne ständiges Polling zu orchestrieren.

Didits KI-nativer Ansatz bedeutet, dass unsere Systeme ständig lernen und sich anpassen, was eine überlegene Genauigkeit und Betrugserkennung bietet. Die klare API-Dokumentation und die entwicklerfreundliche Mentalität, kombiniert mit Funktionen wie Free Core KYC und ohne Einrichtungsgebühren, erleichtern den Einstieg. Unsere Webhooks liefern strukturierte Identitätsdaten, sodass Ihre Anwendung intelligent auf Verifizierungsergebnisse reagieren und Vertrauen in großem Maßstab global automatisieren kann. Ob Sie das Alter mit Didits Altersschätzung überprüfen oder sicherstellen müssen, dass ein Benutzer eine lebende Person ist mit passiver & aktiver Liveness-Prüfung, Didit bietet die Tools und das Echtzeit-Feedback, die für eine robuste Identitätslösung erforderlich sind.

Bereit zum Start?

Bereit, Didit in Aktion zu sehen? Holen Sie sich noch heute eine kostenlose Demo.

Beginnen Sie kostenlos mit der Identitätsprüfung mit Didits kostenlosem Tarif.