Fehlerbehebung

Die häufigsten Probleme mit Webhooks – geordnet nach dem, was du beobachtest. Jeder Abschnitt nennt die Ursache und den nächsten Schritt.

Zuletzt geprüft: 25. September 2026

Es kommt kein Webhook an

Prüfe diese Punkte in der Reihenfolge:

Aktiv?: Der Webhook steht unter Stammdaten auf Aktiv. Ein erfolgreicher Test schaltet einen pausierten Webhook nicht wieder ein.
Quelle und Event: Mindestens eine Quelle und ein Event sind ausgewählt. Der farbige Punkt vor dem Namen zeigt es: gelb = aktiv ohne Events, grün = aktiv mit Events.
Passende Quelle: Die Änderung kam aus der gewählten Quelle. Ist nur REST-API gewählt, lösen Änderungen in der Oberfläche keinen Webhook aus – und umgekehrt.
Erreichbare URL: Die Adresse beginnt mit https:// und ist öffentlich erreichbar. localhost und interne Adressen werden blockiert.
Audit-Log: Unter Audit-Log → Webhooks steht das Endergebnis jeder Zustellung. Laufen noch Wiederholungen, erscheint der Eintrag erst danach – warte die eingestellten Versuche ab, bevor du von einem fehlenden Event ausgehst.

Danach hilft ein Test aus den Einstellungen – Aufruf und Antwort siehst du direkt unter dem Formular.

Fehlercodes im Test oder Audit-Log

TIMEOUT: Dein Endpunkt hat nicht innerhalb des Timeouts (10–60 s) geantwortet. Häufig dauert die Verarbeitung im Request-Handler zu lange — antworte zuerst mit 2xx und verarbeite die Daten danach.
HTTP_401 / HTTP_403: Dein Endpunkt lehnt den Aufruf wegen der Anmeldung oder Zugriffsprüfung ab. Prüfe die in den HTTP-Headern hinterlegten Werte und ob dein Empfänger sie korrekt auswertet. 401/403 wird nicht wiederholt (siehe Erfolgreich oder fehlgeschlagen).
HTTP_404: Der URL-Pfad existiert nicht oder die Route verwendet eine andere HTTP-Methode.
HTTP_405: Dein Endpunkt akzeptiert die konfigurierte Methode nicht. Häufig erwartet die Route GET, während i-Planner standardmäßig POST sendet.
HTTP_5xx: Der Endpunkt hat einen Server-Fehler zurückgegeben — i-Planner wiederholt automatisch. Wenn dein Service nur kurzzeitig gestört ist, erhöhe die Pause zwischen Versuchen (Retry-Backoff).
FETCH_ERROR: Verbindungsabbruch, DNS-Fehler oder TLS-Probleme. Prüfe die DNS-Auflösung sowie Gültigkeit, Hostnamen und Zertifikatskette des Zertifikats.
BLOCKED_PRIVATE_URL: Die Ziel-URL hat zum Zeitpunkt der Auslieferung nicht mehr als öffentlich erreichbar gegolten (z. B. DNS-Auflösung auf eine private IP). Siehe Sichere Ziel-Adresse.

Welche Fehler i-Planner automatisch wiederholt, steht unter Erfolgreich oder fehlgeschlagen.

Der Webhook wurde automatisch deaktiviert

Nach zu vielen Fehlern in Folge – standardmäßig 10 – setzt i-Planner den Webhook auf inaktiv und versucht, die Inhaber der Organisation sowie die hinterlegten E-Mail-Empfänger per E-Mail zu informieren.

Öffne den letzten Fehler im Audit-Log → Webhooks und behebe die Ursache (siehe Fehlercodes).
Sende einen Test, bis er erfolgreich ist.
Stelle den Webhook unter Stammdaten wieder auf Aktiv.

Die Schwelle stellst du unter Erweitert ein – Details unter Auto-Deaktivierung.

Dieselbe Nachricht kommt mehrfach an

Das ist bei Wiederholungen möglich und gewollt: Lieber doppelt als gar nicht. Der Header webhook-id bleibt bei allen Versuchen gleich. Speichere ihn beim Empfänger und ignoriere eine ID, die du schon verarbeitet hast.

Die Reihenfolge stimmt nicht

Wiederholungen und Netzwerklaufzeiten können die Reihenfolge verändern. Sortiere bei Bedarf nach dem Feld timestamp im Body.

Die Signatur passt nicht – für Entwickler

Body verändert: Die Signatur gilt für den unveränderten Roh-Body. Viele Frameworks parsen JSON automatisch – prüfe die Signatur vor dem Parsen.
Falscher Schlüssel: Der HMAC-Schlüssel sind die base64-dekodierten Bytes hinter whsec_, nicht der ganze String.
Zeitfenster: webhook-timestamp liegt außerhalb deines Fensters. Prüfe die Uhrzeit deines Servers; empfohlen sind ± 5 Minuten.
Secret gewechselt: Während einer Rotation stehen zwei Signaturen im Header. Prüfe jede davon, bis eine passt.

Vollständige Anleitung mit Code-Beispielen: Signatur prüfen.

Häufige Fragen

Standardmäßig 30 Tage. Gespeichert wird das Endergebnis je Zustellung, nicht jeder einzelne Versuch. Siehe Zustellungen im Audit-Log.

Nicht direkt – i-Planner ruft nur öffentlich erreichbare Adressen auf. Nutze einen Tunnel wie ngrok oder Cloudflare Tunnel, siehe Lokal testen.

Zurück

Sicherheit