Webhook-Fehler
Symptom A: Webhook-Endpunkt gibt 4xx/5xx zurück
Wie prüfen: Dashboard → Property → Webhooks → Zustellungsprotokoll — zeigt Statuscodes und Antworttexte.
Ursachen und Behebungen:
| Statuscode | Wahrscheinliche Ursache | Behebung |
|---|---|---|
401 | Signaturüberprüfung schlägt fehl | Überprüfen Sie Ihren Verifizierungscode — siehe Webhook-Sicherheit |
400 | Ihr Endpunkt lehnt das Payload-Format ab | Den rohen Körper protokollieren und mit dem Payload-Schema vergleichen |
404 | Endpunkt-URL hat sich geändert | Webhook-URL unter Property → Webhooks → [Webhook] → Bearbeiten aktualisieren |
500 | Fehler in Ihrem Webhook-Handler | Ihre Serverprotokolle auf den Fehler prüfen |
timeout | Ihr Endpunkt braucht zu lange zum Antworten | Sofort mit 200 antworten, asynchron verarbeiten |
Symptom B: Webhook-Signaturüberprüfung schlägt fehl
Ursache: Häufigste Gründe:
- Signatur-String falsch erstellt — muss
{timestamp}.{raw_body}sein (nicht geparste JSON) - Ein anderes Geheimnis verwenden als das im Dashboard angezeigte
- Gepufferten/modifizierten Körper statt der rohen Bytes lesen
Behebung: Stellen Sie sicher, dass Sie den rohen Anfragekörper vor dem JSON-Parsing lesen. 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.
Behebung: Beheben Sie den zugrunde liegenden Fehler (siehe Symptom A). Sobald Ihr Endpunkt 2xx zurückgibt, werden zukünftige Zustellungen sofort erfolgen.
Symptom D: Fehlende Zustellungen — Ereignisse nicht empfangen
Wie prüfen: Vergleichen Sie die Zustellungsprotokolle des Dashboards mit der empfangenen Anzahl Ihres Servers.
Ursache: Einige Ereignisse haben möglicherweise alle Wiederholungsversuche erschöpft (5 Versuche über ~2 Stunden).
Behebung: Property → Webhooks → Zustellungsprotokoll → Filter: Fehlgeschlagen — verwenden Sie die Schaltfläche Wiederholen, um fehlgeschlagene Zustellungen erneut zu senden.