KYB-Webhooks API: Ereignisse, Payload & HMAC-Signatur

Didit-KYB-Webhooks informieren Ihr Backend, wenn sich der Status einer Unternehmensverifizierungs-Sitzung ändert oder wenn ein Prüfer oder das Unternehmensregister die Daten ändert. Unternehmensentitäten haben eigene Ereignisse. Abonnieren Sie die gewünschten Ereignisse über die Webhook-Ziel-API oder in der Business Console.

Ereigniskatalog

Ereignisse auf Sitzungsebene gelten sowohl für Benutzer- als auch für Unternehmenssitzungen. Das Feld session_kind im Payload zeigt an, um welche Sitzungsart es sich handelt. Ereignisse auf Entitätsebene sind von Ereignissen auf Sitzungsebene getrennt.

Ereignisse auf Sitzungsebene

Ereignis	Zeitpunkt der Auslösung
`status.updated`	Der Status einer Sitzung hat sich geändert. Bei Unternehmensverifizierungs-Sitzungen (KYB) enthält der Payload `session_kind: "business"`. Dieses Ereignis sollten Sie für den Fortschritt verfolgen.
`data.updated`	Ein Prüfer hat die Daten des Unternehmensregisters bearbeitet, die Schlüsselpersonen in der Console übersprungen oder neu generiert, oder das Unternehmensregister hat eine Änderung gemeldet (sofern Überwachung des Unternehmensregisters verfügbar ist). Das Feld `trigger` gibt an, welcher Fall zutrifft.

data.updated wird nicht gesendet, wenn der Antragsteller ein Dokument hochlädt oder Schlüsselpersonen einreicht, oder wenn ein AML-Rescan abgeschlossen ist. Verwenden Sie status.updated oder rufen Sie die Sitzungsentscheidung ab, um diesen Fortschritt zu verfolgen.

Ereignisse für Unternehmensentitäten

Ereignis	Zeitpunkt der Auslösung
`business.status.updated`	Der Status der verknüpften Unternehmensentität hat sich geändert (`ACTIVE` / `FLAGGED` / `BLOCKED`).
`business.data.updated`	Die Profilfelder oder aggregierten Zähler der Unternehmensentität haben sich geändert.

Abonnieren Sie auf Ihrem Webhook-Ziel beliebige Kombinationen dieser Ereignisse. Die vollständige Referenz zu den Ereignissen von Unternehmens- und Benutzerentitäten finden Sie unter Entitäts-Webhooks.

Payload-Struktur

Webhooks für Sitzungen verwenden einen flachen Payload ohne data-Wrapper. Der Envelope, die Signatur-Header und alle gemeinsamen Felder sind in der Webhook-Referenz dokumentiert. Eine KYB-Sitzung fügt diese Felder hinzu:

Feld	Typ	Beschreibung
`session_kind`	`"business"`	Ermöglicht einem generischen Handler, zwischen KYC und KYB zu unterscheiden.
`business_session_id`	`uuid`	Entspricht `session_id`.
`vendor_business_id`	string	Ihre Kennung für die Unternehmensentität, sofern bei der Sitzungserstellung angegeben.
`status`	string	Die genaue Bezeichnung, zum Beispiel `"In Progress"`, `"Approved"` oder `"Awaiting User"`. Siehe Status.
`trigger`	string	Optional. Grund für die Auslösung des Webhooks. Bei `data.updated` für KYB: `"console_registry_edit"`, `"console_key_people_skip"`, `"console_key_people_regenerate"` oder `"kyb_registry_change"`.
`decision`	object	Vorhanden, wenn `status` `Approved`, `Declined`, `In Review` oder `Abandoned` ist. Die gleiche Struktur wie `GET /v3/session/{id}/decision/`, siehe das Antwortschema.
`resubmit_info`	object	Vorhanden, wenn `status` `Resubmitted` ist.

`status.updated` für eine KYB-Sitzung

{
  "event_id": "7f3c2c1e-6a1d-4c36-9d8e-0d3b5f4e2a10",
  "webhook_type": "status.updated",
  "session_id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "business_session_id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "session_kind": "business",
  "status": "Approved",
  "created_at": 1776515400,
  "timestamp": 1776515401,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "workflow_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
  "workflow_version": 3,
  "vendor_data": "biz-acme-001",
  "decision": { "...": "abbreviated KYB decision payload" }
}

Der Block decision enthält registry_checks[], key_people_checks[], document_verifications[], aml_screenings[] sowie die übrigen KYB-Arrays.

`data.updated` für eine KYB-Sitzung

data.updated enthält dieselbe flache Struktur wie status.updated, zusätzlich einen trigger, der den Grund der Auslösung angibt. Wenn der Sitzungsstatus Approved, Declined, In Review oder Abandoned ist, enthält der Payload außerdem die aktuelle decision. Rufen Sie die Entscheidung erneut ab, um zu sehen, was sich geändert hat. Der Payload enthält keine Liste changed_fields.

`business.status.updated` und `business.data.updated`

Auch Entitätsereignisse sind flach. Sie enthalten vendor_business_id, vendor_data, status (ACTIVE, FLAGGED oder BLOCKED) und created_at. business.status.updated ergänzt previous_status. business.data.updated ergänzt changed_fields und eine Map changes mit { field: { previous, current } }.

{
  "event_id": "2b9d6f0a-3c41-4e8b-b6a7-5d1e8f9a0c32",
  "webhook_type": "business.status.updated",
  "timestamp": 1776515401,
  "created_at": 1776515400,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "vendor_business_id": "f7a9c1b2-4e6d-4f8a-9c5d-2a1b3c4d5e6f",
  "vendor_data": "biz-acme-001",
  "status": "FLAGGED",
  "previous_status": "ACTIVE"
}

Signaturprüfung

Jeder Webhook wird mit HMAC-SHA256 und dem gemeinsamen Geheimnis Ihres Ziels signiert. Prüfen Sie den unveränderten Body der Anfrage anhand des Headers X-Signature-V2 (empfohlen) und verwerfen Sie Zustellungen, deren X-Timestamp älter als 300 Sekunden ist. In der Webhook-Referenz finden Sie alle Signatur-Header, die Überlappungszeit bei der Rotation des Signaturgeheimnisses und Codebeispiele.

Wiederholungsrichtlinie

Eine Antwort mit 5xx oder 404, ein Timeout oder ein Verbindungsfehler löst bis zu 2 Wiederholungsversuche aus, nach etwa 1 Minute und etwa 4 Minuten. Danach wird die Zustellung verworfen.
Andere Antworten mit 4xx und 3xx werden nicht wiederholt.
Jeder Wiederholungsversuch behält dieselbe event_id. Prüfen Sie Duplikate daher anhand dieser ID.
Sie können eine Zustellung aus dem Zustellungsprotokoll des Ziels erneut senden. Die vollständige Richtlinie finden Sie in der Webhook-Referenz.

curl -X POST https://verification.didit.me/v3/webhook/destinations/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "KYB events",
    "url": "https://yourapp.com/webhooks/didit-kyb",
    "subscribed_events": [
      "status.updated",
      "data.updated",
      "business.status.updated",
      "business.data.updated"
    ]
  }'

Filtern Sie auf Ihrer Seite nach Unternehmenssitzungen, indem Sie in den Ereignissen status.updated und data.updated session_kind === "business" prüfen.

Nächste Schritte

Webhook-Referenz

Ziele, Signatur, Wiederholungen und gängige Muster.

Status

Referenz zu Sitzungs- und Funktionsstatus.

Antwortschema

Dekodierung des KYB-Entscheidungs-Payloads.

Erste Schritte

Funktionen

Unternehmensprofile

Referenz

Konsole

KYB-Webhooks API: Ereignisse, Payload & HMAC-Signatur

Ereigniskatalog

Ereignisse auf Sitzungsebene

Ereignisse für Unternehmensentitäten

Payload-Struktur

`status.updated` für eine KYB-Sitzung

`data.updated` für eine KYB-Sitzung

`business.status.updated` und `business.data.updated`

Signaturprüfung

Wiederholungsrichtlinie

Abonnieren

Nächste Schritte

Webhook-Referenz

Status

Antwortschema

​Ereigniskatalog

​Ereignisse auf Sitzungsebene

​Ereignisse für Unternehmensentitäten

​Payload-Struktur

​status.updated für eine KYB-Sitzung

​data.updated für eine KYB-Sitzung

​business.status.updated und business.data.updated

​Signaturprüfung

​Wiederholungsrichtlinie

​Abonnieren

​Nächste Schritte

Webhook-Referenz

Status

Antwortschema

Ereigniskatalog

Ereignisse auf Sitzungsebene

Ereignisse für Unternehmensentitäten

Payload-Struktur

`status.updated` für eine KYB-Sitzung

`data.updated` für eine KYB-Sitzung

`business.status.updated` und `business.data.updated`

Signaturprüfung

Wiederholungsrichtlinie

Abonnieren

Nächste Schritte