Webhooks

Was passiert hier?

Ein Webhook ist eine URL, an die wir per POST senden, sobald in Ihrer Certivant-Organisation etwas passiert. Anstatt unsere API nach Änderungen abzufragen („Ist die Verifizierung schon fertig?“), geben Sie uns eine URL, und wir informieren Sie in dem Moment, in dem es so weit ist. Webhook-Ereignisse halten Ihre eigenen Systeme synchron: Onboarding-Abläufe für Kunden, AML-Risikodatenbanken, CRM-Markierungen und interne Compliance-Dashboards.

Wo finden Sie es?

KYC → Webhooks in der linken Seitenleiste. (KYB-Ereignisse werden an dieselben Webhook-Endpunkte gesendet. Es gibt keine eigene Webhook-Konfiguration für KYB.)

Einrichtung

const sig = req.headers["x-certivant-signature"];
const expected = hmac("sha256", secret).update(rawBody).digest("hex");
if (!timingSafeEqual(sig, expected)) return 401;

Ereignistypen

Die vollständige Liste und die JSON-Nutzlasten finden Sie unter KYC → Entwickler → Webhook-Ereignisse.

Aufbau der Nutzlast

Jedes Ereignis hat denselben Envelope:

{
  "id": "evt_2k3f9a...",
  "type": "kyc.request.approved",
  "createdAt": "2026-05-27T14:30:00Z",
  "organizationId": "org_abc123",
  "data": { /* event-specific payload */ }
}

Das Feld data unterscheidet sich je Ereignistyp. kyc.request.approved enthält zum Beispiel:

{
  "request": { "id": "kyr_...", "status": "APPROVED", "type": "INDIVIDUAL", ... },
  "applicant": { "id": "ka_...", "fullName": "Jane Doe", "email": "...", ... },
  "decision": { "by": "auto" | "manual", "reviewerId": "user_..." | null, "note": "..." | null },
  "policy": {
    "id": "pol_..." | null,
    "name": "default-kyc-policy",
    "version": 3 | null,
    "isDefault": true,
    "decision": "approve" | "reject" | "escalate" | "live_verification",
    "rulesFired": ["tier1-disqualified", "approve-by-score"],
    "reason": "High-risk country",
    "liveVerificationRequired": true
  }
}

Der Block policy (bei kyc.request.approved / rejected / escalated) zeigt Ihnen, welche Risikorichtlinie über die Anfrage entschieden hat und welche Regeln gegriffen haben. isDefault: true bedeutet, dass die Standardrichtlinie von Certivant lief. id und version sind dann die Zeile der Standardrichtlinie Ihrer Organisation oder null, wenn sie noch nicht angelegt wurde. Eine eigene Richtlinie meldet ihre gespeicherte id, ihren name und ihre version. rulesFired listet die IDs der zutreffenden Regeln in der Auswertungsreihenfolge auf. Steuern Sie Ihre nachgelagerte Automatisierung darüber. reason ist die Begründung der entscheidenden Regel, sofern sie eine gesetzt hat. decision: "live_verification" (mit liveVerificationRequired: true bei kyc.request.escalated) bedeutet, dass die Richtlinie vor einer endgültigen Entscheidung eine Live-ID-Verifizierung verlangt. Die Anfrage wartet dann in der manuellen Prüfung, bis der Anruf entschieden hat. Siehe Risikorichtlinie entwerfen.

Wenn Sie im Partnermodus arbeiten (eine Organisation bedient viele Endkunden), enthält jeder Ereignis-Envelope außerdem subTenantName und subTenantExternalId. Das sind die Markierungen, die bei der Anlage der Anfrage über die API gesetzt wurden. So kann Ihr Handler das Ergebnis dem richtigen Endkunden zuordnen. Die genaue Position der Felder finden Sie in der Entwickler-Referenz für Webhooks.

Wiederholungen

Wenn Ihr Endpunkt einen Status ungleich 2xx zurückgibt (oder das Zeitlimit überschritten wird), wiederholen wir den Versand mit exponentiellem Backoff:

attempt 1: immediately
attempt 2: 30 seconds later
attempt 3: 5 minutes later
attempt 4: 30 minutes later
attempt 5: 2 hours later
attempt 6: 6 hours later
attempt 7: 24 hours later

Nach 7 fehlgeschlagenen Versuchen markieren wir das Ereignis als permanently_failed und versuchen es nicht mehr. Fehlgeschlagene Ereignisse erscheinen im Webhook-Dashboard mit dem letzten Fehler. Mit Wiederholen lösen Sie jedes davon manuell erneut aus.

Mehrere Endpunkte

Sie können mehrere Endpunkte registrieren, zum Beispiel einen für Ihr CRM und einen für Ihren AML-Data-Lake. Jeder kann andere Ereignistypen abonnieren. Jeder Endpunkt hat ein eigenes Signaturgeheimnis. Das Rotieren eines Geheimnisses bricht die anderen nicht.

Webhooks je Formular

Der organisationsweite Webhook sendet für jedes relevante Ereignis. Öffentliche Formulare können zusätzlich eine URL für den Webhook je Formular in ihren Einstellungen haben. Das ist nützlich, wenn ein Formular ein separates System speist. Webhooks je Formular laufen zusätzlich zu den organisationsweiten.

Die Seite KYC → Webhooks listet beides nun an einer Stelle auf: Ihre URL des organisationsweiten Webhooks oben und darunter eine Zeile für jede URL des Webhooks je Formular. So sehen Sie alle Stellen, an die Ereignisse zugestellt werden, ohne die Einstellungen einzelner Formulare durchsuchen zu müssen.

Das Webhook-Dashboard

KYC → Webhooks listet jeden Endpunkt mit:

• Endpunkt-URL und einem verständlichen Namen.
• Status — aktiv / pausiert / fehlerhaft.
• Letzte Zustellung — wann das letzte Ereignis gesendet wurde.
• Erfolgsquote — Anteil der Versuche, die in den letzten 7 Tagen mit 2xx antworteten.
• Letzte Zustellungen — Tabelle mit den letzten Ereignissen, Statuscode, Latenz und Antworttext.

Pausieren Sie einen Endpunkt, um die Zustellung zu stoppen, ohne die Konfiguration zu verlieren.

Fehlerbehebung

Mein Endpunkt wird überhäuft

Endpunkte werden einmal pro Ereignis aufgerufen. Eine ausgelastete Organisation kann aber dutzende Ereignisse pro Minute auslösen. Machen Sie Ihren Endpunkt asynchron: Nehmen Sie den POST an, bestätigen Sie sofort mit 2xx und verarbeiten Sie die Nutzlast außerhalb des Anfragezyklus. Wenn Sie uns bremsen müssen, setzen Sie die Option Maximale gleichzeitige Zustellungen je Endpunkt.

Die Signaturprüfung schlägt immer wieder fehl

Drei häufige Ursachen:

1. Der Text wird vor der Signaturprüfung geparst. Verwenden Sie die Rohbytes. Bei Express mit body-parser setzen Sie für die Webhook-Route gezielt bodyParser.raw({ type: 'application/json' }).
2. Falsches Geheimnis. Rotieren Sie es und fügen Sie es erneut ein.
3. Der Text wird durch eine Middleware verändert (gzip, BOM, Kodierung). Die Signatur bezieht sich auf die exakten Bytes, die wir gesendet haben.

Ereignisse wirken doppelt

Wiederholungen bei langsamen Antworten. Verwenden Sie event.id als Schlüssel für die Idempotenz.

Die Reihenfolge der Ereignisse ist wichtig, aber sie kommen durcheinander

Wir garantieren keine strikte Reihenfolge über alle Ereignistypen hinweg. Für die Reihenfolge je Antragsteller verwenden Sie das Feld createdAt des Ereignisses. Die Reihenfolge innerhalb des Lebenszyklus eines einzelnen Antragstellers ist monoton.

Verwandte Themen

• Audit-Protokoll — jede Auslösung eines Webhooks wird auch hier protokolliert.
• Entwickler (API-Schlüssel) — wenn Sie den Status über REST abrufen möchten, statt Nachrichten zu empfangen.
• Formulare — Vorschau & Veröffentlichung — Webhooks je Formular.