# Webhook-Zustellungen schlagen fehl ## 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](/help/howto/webhooks); die technische Referenz inklusive Signatur-Prüfung unter [Webhook-Referenz](/api/webhooks). --- ## 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: Auf der Endpoint-Detailseite kannst du das Signing-Secret rotieren. Das neue Secret (Format `whsec_...`) wird genau einmal angezeigt. 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. Ein Test-Event bestätigt, dass die Prüfung wieder durchläuft. Details zum Signatur-Verfahren (Standard-Webhooks, HMAC-SHA256): [Webhook-Referenz](/api/webhooks). --- ## 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).