Webhook-Fehler
Symptom A: Webhook-Endpunkt gibt 4xx/5xx zurück
Diagnose: Dashboard → Eigenschaft → Webhooks → Zustellungsprotokoll – zeigt Statuscodes und Antworttexte.
Ursachen und Lösungen:
| Statuscode | Wahrscheinliche Ursache | Lösung |
|---|---|---|
401 | Signaturüberprüfung schlägt fehl | Überprüfen Sie Ihren Verifizierungscode – siehe Webhook-Sicherheit |
400 | Ihr Endpunkt lehnt das Nutzlastformat ab | Protokollieren Sie den Rohtext und vergleichen Sie mit dem Nutzlast-Schema |
404 | Endpunkt-URL hat sich geändert | Aktualisieren Sie die Webhook-URL in Eigenschaft → Webhooks → [Webhook] → Bearbeiten |
500 | Fehler in Ihrem Webhook-Handler | Prüfen Sie Ihre Server-Logs auf den Fehler |
timeout | Ihr Endpunkt benötigt zu lange für die Antwort | Antworten Sie sofort mit 200 und verarbeiten Sie asynchron |
Symptom B: Webhook-Signaturüberprüfung schlägt fehl
Ursache: Häufigste Gründe:
- Signing-String falsch aufgebaut – muss
{timestamp}.{raw_body}sein (nicht gepartes JSON) - Verwendung eines anderen Secrets als dem im Dashboard angezeigten
- Gepufferter/veränderter Body wird statt der Roh-Bytes gelesen
Lösung: Stellen Sie sicher, dass Sie den rohen Request-Body lesen, bevor JSON geparst wird. In Express:
// MUSS Raw-Body-Middleware verwenden
app.use('/webhooks', express.raw({ type: '*/*' }));
Symptom C: Webhook-Zustellungen sind verzögert
Ursache: ConsentForge wiederholt fehlgeschlagene Zustellungen mit exponentiellem Backoff – Verzögerungen sind nach anfänglichen Fehlern zu erwarten.
Lösung: Beheben Sie den zugrunde liegenden Fehler (siehe Symptom A). Sobald Ihr Endpunkt 2xx zurückgibt, erfolgen zukünftige Zustellungen sofort.
Symptom D: Fehlende Zustellungen – Ereignisse werden nicht empfangen
Diagnose: Vergleichen Sie die Anzahl der Einträge im Dashboard-Zustellungsprotokoll mit der Anzahl der auf Ihrem Server empfangenen Nachrichten.
Ursache: Einige Ereignisse haben möglicherweise alle Wiederholungsversuche erschöpft (5 Versuche über ~2 Stunden).
Lösung: Eigenschaft → Webhooks → Zustellungsprotokoll → Filter: Fehlgeschlagen – verwenden Sie die Schaltfläche Wiederholen, um fehlgeschlagene Zustellungen erneut zu senden.