Symptom
Dein System erhält keine (oder nicht mehr alle) Webhook-Events. Im Zustell-Log stehen fehlgeschlagene Zustellungen, oder der Endpoint wurde automatisch pausiert.
Grundlagen zum Einrichten stehen unter Webhooks einrichten; die technische Referenz inklusive Signatur-Prüfung unter Webhook-Referenz.
Schritt 1: Zustell-Log lesen
Öffne Einstellungen > Webhooks und dann die Detailseite des Endpoints. Das Zustell-Log zeigt pro Zustellung den Status, den HTTP-Antwortcode deines Servers und einen Ausschnitt der Antwort. Damit findest du fast jede Ursache:
- Timeout oder Verbindungsfehler: Dein Server war nicht erreichbar oder hat zu langsam geantwortet.
- HTTP 4xx: Dein Server lehnt die Anfrage ab. Häufig eine fehlgeschlagene Signatur-Prüfung (Schritt 3), ein falscher Pfad (404) oder eine Authentifizierung, die den Webhook blockiert (401/403).
- HTTP 5xx: Dein Server nimmt an, stürzt aber bei der Verarbeitung ab.
Schritt 2: Endpoint prüfen
Dein Endpoint muss über HTTPS erreichbar sein, POST-Requests annehmen und schnell mit einem Status 2xx antworten. Bewährte Praxis: Event sofort entgegennehmen, mit 2xx quittieren und die eigentliche Verarbeitung danach im Hintergrund erledigen. Lange Verarbeitung vor der Antwort führt zu Timeouts, die als Fehlschlag zählen.
Mit dem Test-Event auf der Detailseite prüfst du Erreichbarkeit und Signatur, ohne auf ein echtes Ereignis zu warten.
Schritt 3: Signatur-Fehler beheben
Wenn dein Server Zustellungen wegen ungültiger Signatur ablehnt, passt das gespeicherte Secret nicht zum Endpoint. Typische Auslöser: Das Secret wurde beim Anlegen nicht (vollständig) kopiert, ein altes Secret nach einer Rotation, oder der Empfänger prüft gegen den veränderten statt den rohen Request-Body.
So kommst du zurück auf einen sauberen Stand:
Secret rotieren
Auf der Endpoint-Detailseite kannst du das Signing-Secret rotieren. Das neue Secret (Format
whsec_...) wird genau einmal angezeigt.Empfänger aktualisieren
Hinterlege das neue Secret in der Konfiguration deines Empfängers und stelle sicher, dass die Prüfung über den unveränderten Request-Body läuft.
Test-Event senden
Ein Test-Event bestätigt, dass die Prüfung wieder durchläuft.
Details zum Signatur-Verfahren (Standard-Webhooks, HMAC-SHA256): Webhook-Referenz.
Wiederholungen und automatische Pause
Du musst fehlgeschlagene Zustellungen nicht sofort retten:
- Nach einem Fehlschlag wiederholt die Plattform die Zustellung automatisch nach einem festen Zeitplan mit wachsenden Abständen (nach 1 Minute, dann 5, 30, 120 und zuletzt 720 Minuten).
- Schlagen 15 Zustellungen in Folge fehl, wird der Endpoint automatisch pausiert, damit dein Log nicht endlos voll läuft. Behebe die Ursache und aktiviere den Endpoint auf der Detailseite wieder.
- Einzelne Zustellungen kannst du auf der Detailseite manuell erneut zustellen, zum Beispiel nachdem dein Server wieder läuft.
Bekannte Ursachen
| Ursache | Symptom | Lösung |
|---|---|---|
| Server nicht erreichbar | Timeout/Verbindungsfehler im Log | Erreichbarkeit und Firewall prüfen |
| Verarbeitung vor der Antwort | Sporadische Timeouts | Erst 2xx quittieren, dann verarbeiten |
| Falsches Secret | 4xx, Empfänger meldet Signatur-Fehler | Secret rotieren und neu hinterlegen |
| Body verändert geprüft | Signatur-Fehler trotz richtigem Secret | Rohen Request-Body prüfen |
| Endpoint pausiert | Keine neuen Zustellungen mehr | Ursache beheben, Endpoint reaktivieren |
| Fehlende Berechtigung | Webhook-Verwaltung nicht sichtbar | Admin um Zugriff bitten |
Die Verwaltung von Webhooks erfordert die entsprechende Berechtigung (standardmäßig Inhaber:in und Admins).