Wenn ein Webhook nie ankommt

Gehen Sie es der Reihe nach durch: das Zustellprotokoll, der Ereignisname, die Firewall, die Signatur. Der Tab Deliveries sagt Ihnen, ob Didit ihn gesendet hat, was das Problem sofort halbiert.

Verfasst vom Didit-Support · Aktualisiert am 19. August 2026

#Schritt 1: Hat Didit versucht, ihn zu senden?

Öffnen Sie das Ziel unter API & Webhooks und schauen Sie sich den Tab Deliveries an. Jeder Versuch wird einzeln protokolliert, mit der Antwort.

1234

1. Last sent zeigt, ob Didit es überhaupt versucht hat.
2. View stats zeigt die Versuche und Fehlschläge für dieses Ziel.
3. Eine Testzustellung trennt Ihren Endpunkt vom Ereignis selbst.
4. Ein Ziel, das ständig fehlschlägt, kann deaktiviert werden, während Sie es beheben.

Diese eine Prüfung halbiert das Problem sofort:

• Kein Versuch protokolliert → das Ereignis wurde für dieses Ziel nie erzeugt. Weiter zu Schritt 2.
• Versuch protokolliert, fehlgeschlagen → Didit hat gesendet, und Ihre Seite hat abgelehnt oder nicht empfangen. Weiter zu Schritt 3.
• Versuch protokolliert, 2xx → er wurde erfolgreich zugestellt. Das Problem liegt in Ihrem Handler, nicht in der Zustellung.

#Schritt 2: Kein Versuch wurde protokolliert

In der Reihenfolge der Wahrscheinlichkeit:

1. Das Ereignis ist nicht abonniert. Es gibt kein Wildcard - jede Ereignisfamilie muss explizit aufgeführt werden. Und ein Name, der nicht existiert (session.status.updated, kyc.completed), erhält stillschweigend nichts. Prüfen Sie gegen die Ereignisliste.
2. Falsche Anwendung. Ziele gehören zu einer Anwendung. Wenn Ihre Sessions unter einer anderen Anwendung laufen als das Ziel, wird niemals ein Ereignis dort ankommen. Das ist die häufigste Ursache, wenn scheinbar alles korrekt konfiguriert ist.
3. Es hat sich nichts geändert. Webhooks feuern bei Änderungen. Eine Session, die sich nicht bewegt hat, oder ein AML-Monitoring-Re-Screening, das nichts über dem Schwellenwert gefunden hat, erzeugt korrekterweise kein Ereignis.
4. Der Status, auf den Sie warten, ist noch nicht eingetreten. Eine Session bei In Progress ist nicht abgeschlossen. Siehe wenn eine Session nie abgeschlossen wird.

#Schritt 3: Die Zustellung wurde versucht und ist fehlgeschlagen

Ein 404 bedeutet, dass die Anfrage etwas erreicht hat, das Ihre Route nicht besaß. Prüfen Sie:

• Den exakten Pfad, einschließlich eines abschließenden Schrägstrichs. Ein Framework, das /hook auf /hook/ umleitet, kann einen funktionierenden Endpunkt in einen 404 oder einen verlorenen Body verwandeln.
• Ob die URL öffentlich ist. Ein lokaler oder Staging-Host, der aus dem Internet nicht erreichbar ist, scheitert auf diese Weise.
• Ob ein Proxy, Load Balancer oder pfadbasierter Router vor Ihrer App diesen Pfad woanders hinsendet.

Ein 5xx bedeutet, dass Ihr Handler einen Fehler geworfen hat. Protokollieren Sie den rohen Body vor dem Parsen, damit Sie sehen können, was tatsächlich ankam.

Ein Timeout bedeutet, dass Sie nicht schnell genug geantwortet haben. Geben Sie zuerst 2xx zurück, verarbeiten Sie danach.

Gar nichts / Connection refused bedeutet, dass Ihr Edge es blockiert hat. Didit liefert von der statischen IP 18.203.201.92 mit einem DiditWebhook/2.0-User-Agent aus. Wenn Sie hinter Cloudflare oder einer WAF mit einer Default-Deny-Haltung stehen, erlauben Sie diese IP für den empfangenden Hostnamen.

#Der Klassiker: automatische Zustellung liefert 404, aber Resend funktioniert

Das kommt oft genug vor, um es zu benennen. Die automatisierte Zustellung schlägt mit einem 404 fehl, dann funktioniert ein Klick auf Resend für dasselbe Ereignis.

Diese Kombination bedeutet, dass sowohl der Payload als auch Ihr Endpunkt in Ordnung sind - der Unterschied liegt also am Timing oder am Pfad, nicht am Inhalt. Prüfen Sie:

• Ein Deploy oder Neustart im Moment der ursprünglichen Zustellung. Resend funktioniert später, weil die App wieder läuft.
• Ein Cold Start, der das Timeout Ihrer Plattform überschritten hat - häufig bei Serverless mit einem langsamen ersten Aufruf.
• Pfadbasiertes Routing, das sich zwischen den beiden Versuchen geändert hat, oder eine Regel, die nur bei manchen Anfragen greift.
• Rate Limiting oder Bot-Schutz an Ihrem Edge, der den manuellen Resend durchgelassen hat, weil er einzeln statt in einem Schwall ankam.

Der Tab Deliveries zeigt beide Versuche mit ihren Zeitstempeln - vergleichen Sie sie mit Ihren eigenen Deploy- und Fehlerprotokollen für diese Minute.

#Signaturprüfung schlägt fehl

Fast immer eine von drei Ursachen:

1. Sie haben neu serialisiertes JSON gehasht. HMAC-en Sie die rohen Request-Body-Bytes exakt so, wie sie empfangen wurden. Parsen und erneutes Serialisieren ändert Leerzeichen und Schlüsselreihenfolge, und die Signatur stimmt nicht mehr überein. Die meisten Frameworks benötigen eine explizite Konfiguration, um Ihnen den rohen Body zu liefern.
2. Falsches Secret. Das Signing-Secret ist pro Ziel eindeutig, und es ist nicht Ihr API-Schlüssel. Zwei Ziele haben zwei verschiedene Secrets.
3. Falsche Annahme über die Kodierung. Wenn Sie unsicher sind, ob das Secret als wörtliche Zeichenfolge verwendet wird oder erst dekodiert werden muss, raten Sie nicht - folgen Sie exakt der Referenz zur Signaturprüfung, und protokollieren Sie beim Debuggen den rohen Body, damit Sie vergleichen können.

#Zwei Wiederholungen sind keine Warteschlange

Bei einem 5xx, 404, Timeout oder Verbindungsfehler wiederholt Didit zweimal - grob nach 1 Minute und dann nach weiteren 4 Minuten - und verwirft die Zustellung anschließend. War Ihr Endpunkt länger als das nicht erreichbar, sind diese Ereignisse endgültig verloren.

Bauen Sie einen Abgleichpfad: pollen Sie beim Start den Decision-Endpoint für jede Session, für die Sie keinen finalen Status halten. Behandeln Sie Webhooks als schnellen Pfad und Polling als Absicherung.

#Testen, ohne Verifizierungen durchzuführen

Try Webhook auf der Zielseite sendet ein vollständig ausgefülltes Ereignis der von Ihnen gewählten Art - approved, declined, in review, KYB, entity, transaction. Nutzen Sie es, um Ihren Endpunkt, die Signaturprüfung und den Handler zu belegen, bevor eine echte Session davon abhängt.

Die Sandbox ist die andere Hälfte davon: eine Sandbox-Session sendet echte Webhooks mit "environment": "sandbox", sodass Sie den gesamten Pfad kostenlos durchgängig testen können. Siehe Testen in der Sandbox.