Verifizierungsergebnisse mit Webhooks erhalten
Didit schickt Ihnen keine E-Mail, wenn sich der Status einer Verifizierung ändert: richten Sie einen Webhook ein, damit Ihr Backend in dem Moment davon erfährt, in dem es passiert, und prüfen Sie die Signatur, bevor Sie ihm vertrauen.
Ein Webhook ist eine HTTP-Anfrage, die Didit an Ihre URL sendet, wenn sich etwas ändert. Fügen Sie ein Ziel unter API & Webhooks hinzu, abonnieren Sie die gewünschten Ereignisse - es gibt kein Wildcard, listen Sie jedes einzeln auf - speichern Sie das Signing-Secret, und prüfen Sie die Signatur, bevor Sie irgendetwas verarbeiten.
Didit sendet keine E-Mail, wenn eine Session zu In Review oder Declined wechselt. Um in dem Moment davon zu erfahren, in dem sich ein Status ändert, ohne die Konsole zu aktualisieren, richten Sie einen Webhook ein - eine URL auf Ihrem Server, an die Didit das Update automatisch sendet.
Webhooks sind das empfohlene Integrationsmuster. Das Pollen des Decision-Endpoints funktioniert als Fallback, ist aber langsamer, kostet mehr Anfragen und verpasst Ereignisse, die ausschließlich per Webhook zugestellt werden - Datenbearbeitungen durch einen Prüfer, Statusänderungen bei Transaktionen und Änderungen auf Entity-Ebene.
#Einrichtung
- Zu API & Webhooks gehen
Öffnen Sie in der Business Console die Anwendung, für die Sie Ereignisse empfangen möchten, und gehen Sie dann zu API & Webhooks.
- Ein Ziel hinzufügen
Geben Sie ihm eine Bezeichnung, die öffentliche HTTPS-URL Ihres Endpunkts, und wählen Sie die gewünschten Ereignisse aus - mindestens Statusänderungen von Sessions.
- Das Signing-Secret speichern
Das Ziel zeigt Ihnen einmalig ein Secret. Speichern Sie es - Ihr Server nutzt es, um zu bestätigen, dass eine Anfrage tatsächlich von Didit stammt und nicht von einem Nachahmer. Vollständige Prüfschritte: Signaturprüfung.
- Testen
Nutzen Sie Try Webhook auf derselben Seite, um ein vollständig ausgefülltes Testereignis - approved, declined, in review, KYB, entity und transaction Szenarien - an Ihren Endpunkt zu senden. So können Sie Ihre Integration validieren, ohne eine echte Verifizierung durchzuführen.
- Add destination registriert die URL, an die Didit Ergebnisse sendet.
- Prüfen Sie jede Zustellung gegen dieses Signing-Secret, bevor Sie ihr vertrauen.
- Wählen Sie, welche Ereignisse ein Ziel empfängt.
- Test Webhook sendet einen Beispiel-Payload, damit Sie bestätigen können, dass Ihr Endpunkt ihn akzeptiert.
#Die Ereignisse, die Sie abonnieren können
Es gibt kein Wildcard - listen Sie jede Ereignisfamilie auf, die Sie möchten. Sie auf mehrere Ziele zu verteilen ist in Ordnung und oft übersichtlicher.
| Ereignis | Feuert wenn |
|---|---|
status.updated | Sich der Status einer KYC- oder KYB-Session ändert. Das, das Sie fast sicher wollen |
data.updated | Verifizierungsdaten nach der Erstellung bearbeitet werden - ein Prüfer korrigiert ein Feld |
user.status.updated | Ein konsolidierter Nutzer zwischen ACTIVE, FLAGGED und BLOCKED wechselt |
user.data.updated | Sich Profil, Zähler oder Kennungen eines konsolidierten Nutzers ändern |
business.status.updated | Ein konsolidiertes Unternehmen den Status wechselt |
business.data.updated | Sich die Daten eines konsolidierten Unternehmens ändern |
transaction.created | Eine Transaktion erstellt wird und ihr erstes Urteil bereitsteht |
transaction.status.updated | Sich der Status einer Transaktion danach ändert |
travel_rule.status.updated | Sich der Status eines Travel-Rule-Austauschs ändert |
Es gibt kein session.status.updated oder kyc.completed. Wenn Sie einen Namen abonniert haben, der
nicht in dieser Liste steht, erhalten Sie nichts - und es wird genau wie ein Zustellfehler aussehen.
Prüfen Sie zuerst den Namen.
#Was Ihr Endpunkt tun sollte
- Prüfen Sie zuerst die Signatur. HMAC-en Sie den rohen Request-Body - niemals eine neu serialisierte Version des geparsten JSON, denn erneutes Serialisieren ändert die Bytes und die Signatur stimmt nicht mehr überein. Verwenden Sie einen zeitkonstanten Vergleich.
- Geben Sie schnell 2xx zurück. Erledigen Sie aufwendige Arbeit asynchron, nachdem Sie geantwortet haben.
- Seien Sie idempotent. Schlüsseln Sie über die Event-ID, oder über Session-ID + Status + Webhook-Typ. Wiederholungen und Duplikate kommen vor.
- Behandeln Sie jeden Status, der Sie interessiert, einschließlich derer, die lange nach dem Onboarding eintreffen - eine genehmigte Session kann später durch laufendes AML-Monitoring zu In Review wechseln.
- Nur HTTPS. Reine HTTP-Endpunkte werden nicht unterstützt.
#Wiederholungen
Bei einem 5xx, einem 404, einem Timeout oder einem Verbindungsfehler wiederholt Didit zweimal:
- Erste Wiederholung etwa 1 Minute nach dem ursprünglichen Fehlschlag
- Zweite Wiederholung etwa 4 Minuten danach
Danach wird die Zustellung verworfen. Jeder Versuch wird separat im Tab Deliveries des Ziels protokolliert, sodass Sie genau sehen können, was passiert ist, statt zu raten.
Zwei Wiederholungen über fünf Minuten sind keine dauerhafte Warteschlange. Ist Ihr Endpunkt eine Stunde lang nicht erreichbar, sind diese Ereignisse verloren. Gleichen Sie beim Start ab, indem Sie den Decision-Endpoint für Sessions pollen, für die Sie keinen finalen Status haben - Webhooks sind der schnelle Pfad, nicht der einzige.
#Hinter einer Firewall oder WAF
Didit liefert von der statischen IP 18.203.201.92 mit einem DiditWebhook/2.0-User-Agent aus. Wenn Ihr Edge unbekannte Clients blockiert - Cloudflares Standardhaltung zum Beispiel - erlauben Sie diese IP für den empfangenden Hostnamen, oder Zustellungen scheitern, bevor sie Ihren Code erreichen.
#Noch kein Backend?
Sie können Ergebnisse weiterhin manuell im Bereich Verifications der Konsole überwachen, während Sie eines aufbauen, oder in der Zwischenzeit einen No-Code-Verifizierungslink nutzen.
#Nächste Schritte
- Wenn ein Webhook nicht ankommt: wenn ein Webhook nie ankommt
- Verstehen, was jeder Status bedeutet, sobald er ankommt: was jeder Session-Status bedeutet
- Vollständige technische Referenz, einschließlich Codebeispielen zur Signaturprüfung: Webhooks