Zustellung

Hier erfährst du, wann eine Zustellung erfolgreich ist, welche Fehler automatisch erneut versucht werden und wann i-Planner einen Webhook zum Schutz vor weiteren Fehlern deaktiviert.

Zuletzt geprüft: 15. September 2026

So wird ein Webhook zugestellt

Wenn ein ausgewähltes Event eintritt, prüft i-Planner zunächst die Webhook-Einstellungen, das Zustelllimit und die benötigten Daten. Erst wenn diese Prüfungen erfolgreich sind, wird die Nachricht in die Warteschlange gestellt. Vor dem ersten Versand wartet das System die eingestellte Verzögerung von 1 bis 10 Sekunden ab. Das ist hilfreich, wenn bei einer Änderung kurz nacheinander mehrere zusammengehörige Daten gespeichert werden.

Nach Aufnahme in die Warteschlange versucht i-Planner die Zustellung nach den unten beschriebenen Regeln. Eine tatsächliche Ankunft beim Empfänger ist nicht garantiert: Dauerhafte Ablehnungen, Sicherheitsfehler oder ausgeschöpfte Wiederholungen können eine Zustellung beenden. Vor Aufnahme in die Warteschlange können beispielsweise das Zustelllimit oder fehlende Daten einen Versand verhindern. Durch Wiederholungen kann dieselbe Nachricht mehrfach bei dir ankommen. Der Header webhook-id bleibt dabei gleich und ist der Schlüssel, um Duplikate zu erkennen (siehe Empfehlungen für Entwickler).

Der HTTP-Aufruf enthält:

HTTP-Methode: Die in den HTTP-Einstellungen gewählte Methode — POST (Standard), PUT oder PATCH.
Ziel-URL: Die konfigurierte URL. Sie muss mit https:// beginnen und öffentlich erreichbar sein (siehe Sichere Ziel-Adresse).
Content-Type: application/json (Standard) · application/x-www-form-urlencoded · text/plain — bestimmt die Body-Codierung.
Statische Header: Alle unter HTTP-Header hinterlegten Namen und Werte werden mitgesendet, beispielsweise Authorization oder X-API-Key.
Body: Der Webhook-Envelope mit genau request_id · event_name · timestamp · payload in der gewählten Codierung. application/json und text/plain enthalten denselben JSON-Text; bei application/x-www-form-urlencoded werden Objekte als JSON-Werte form-codiert.
Signatur: Die Header webhook-version, webhook-id, webhook-timestamp und webhook-signature. Die Prüfung ist unter Sicherheit beschrieben.

Erfolgreich oder fehlgeschlagen

i-Planner wertet die Antwort deines Endpunkts nach HTTP-Status-Code aus:

2xx: Erfolg — die Zustellung gilt als erfolgreich und steht im Audit-Log als Erfolg. Der Fehlerzähler des Webhooks wird zurückgesetzt. Lesbare Antwortdetails werden nur zur Diagnose gespeichert, nicht zur Erfolgsprüfung verwendet.
4xx: Endgültiger Fehler, außer 408 und 429 — i-Planner geht davon aus, dass dein Endpunkt den Aufruf bewusst ablehnt, zum Beispiel wegen Anmeldung, Datenprüfung oder URL-Pfad. Es wird nicht wiederholt.
408 / 429: Vorübergehender Fehler — Zeitüberschreitung oder zu viele Anfragen beim Empfänger. i-Planner wiederholt den Versuch nach der eingestellten Pause.
5xx: Vorübergehender Fehler — wird automatisch wiederholt.
Timeout: Wenn dein Endpunkt nicht innerhalb der eingestellten Zeit antwortet (10–60 s), bricht i-Planner ab und behandelt das wie 5xx — es wird wiederholt.
Netzwerkfehler: DNS-Fehler, Verbindungsabbruch, TLS-Fehler — wird wiederholt.
Blockierte URL: Wenn die Ziel-URL bei der erneuten Prüfung nicht mehr als öffentlich gilt (siehe URL-Validierung), bricht i-Planner sofort ab. Es wird nicht wiederholt.

Automatische Wiederholungen

In den Erweiterten Einstellungen legst du drei Werte fest:

Timeout (10–60 s): Wie lange i-Planner pro Versuch auf eine Antwort wartet. Standard 10 s. Empfänger-Tipp: verarbeite eingehende Webhooks asynchron und antworte sofort, sonst frisst die Verarbeitungszeit das Timeout-Budget auf.
Wiederholungen (0–10): Zusätzliche Versuche bei 5xx, Timeout oder Netzwerkfehler. 3 × bedeutet: ein Erstversuch und bis zu 3 Wiederholungen — insgesamt 4 Zustellversuche. 0 × deaktiviert Wiederholungen.
Pause zwischen Versuchen (Retry-Backoff, 0–600 s): Wartezeit zwischen den Versuchen, Standard 60 s. Erhöhe diesen Wert, wenn dein Backend nach einem Ausfall länger zum Hochfahren braucht.

i-Planner wartet zwischen den Versuchen immer die eingestellte Zeit. Bei einer 4xx-Antwort außer 408/429 oder einer aus Sicherheitsgründen blockierten URL wird nicht erneut gesendet, weil eine Wiederholung den Konfigurationsfehler nicht beheben würde.

So sieht der Ablauf mit den Standardwerten aus (3 Wiederholungen, 60 s Pause, 10 s Timeout), wenn dein Endpunkt dauerhaft mit 5xx antwortet:

0 s: Erstversuch, sobald die konfigurierte Verzögerung (1–10 s) abgelaufen ist.
+ 60 s: 1. Wiederholung.
+ 120 s: 2. Wiederholung.
+ 180 s: 3. und letzte Wiederholung. Danach ist das Ergebnis final und steht im Audit-Log, der Fehlerzähler des Webhooks steigt um eins.

Antwortet dein Endpunkt nicht, kommt pro Versuch zusätzlich der Timeout hinzu — im Beispiel also bis zu 10 s je Versuch.

Zustellungen im Audit-Log

Für eingeplante Webhook-Zustellungen schreibt i-Planner einen Eintrag ins Audit-Log — nicht für jeden einzelnen Versuch. Du findest die Liste unter Audit-Log → Webhooks. Dort siehst du das endgültige Ergebnis: erfolgreich, endgültig fehlgeschlagen oder nach allen Wiederholungen weiterhin fehlgeschlagen. Ein Event, das schon vor Aufnahme in die Warteschlange abgewiesen wurde, ist keine Zustellung und erscheint nicht als zugestellte Nachricht. Über den Filter Status grenzt du auf Erfolg oder Fehlgeschlagen ein.

Zeitpunkt: Wann die Zustellung abgeschlossen wurde.
Trigger: Technischer Event-Name, z. B. customers.insert.
Methode / Ziel: HTTP-Methode und Host der Ziel-URL.
Status: HTTP-Code der finalen Antwort. Bei reinen Netzwerkfehlern oder Timeouts steht hier Fehler.
Versuch: Wie viele Anläufe i-Planner unternommen hat, bevor dieser Status final wurde.
Dauer: Zeit in Millisekunden vom Absenden bis zur Antwort (oder zum Abbruch).
Request-ID: Die request_id des Events — dieselbe, die im Body an deinen Empfänger geht.
Detail: Ein Klick auf den Eintrag zeigt den gesendeten Aufruf und die empfangene Antwort sowie bei Misserfolg den Fehlertyp: HTTP_<Code> · TIMEOUT · FETCH_ERROR (Netzwerkproblem) · BLOCKED_PRIVATE_URL (URL ist nicht öffentlich). Werte selbst konfigurierter HTTP-Header werden im Log grundsätzlich maskiert.

Standard-Aufbewahrung der Log-Einträge: 30 Tage.

Auto-Deaktivierung

Im Abschnitt Erweitert legst du fest, nach wie vielen aufeinanderfolgenden Fehlern der Webhook automatisch deaktiviert wird. Nach einer erfolgreichen Zustellung beginnt der Fehlerzähler wieder bei null.

0: Auto-Deaktivierung aus. Der Webhook bleibt aktiv, auch bei dauerhaften Fehlern.
1 – 10: Sobald der Zähler die Schwelle erreicht, setzt i-Planner den Webhook auf inaktiv, vermerkt den letzten Fehler und versucht, den Inhaber sowie zusätzlich hinterlegte E-Mail-Empfänger zu informieren. Nach der Behebung kannst du den Webhook wieder aktivieren.

Auto-Deaktivierung schützt vor zwei Szenarien:

Empfänger dauerhaft offline — verhindert, dass i-Planner für jedes weitere Event einen Fehlversuch produziert.
Falsche Konfiguration entdeckt — der Inhaber und zusätzlich hinterlegte Empfänger werden informiert, statt nur einen wachsenden Fehler-Stapel im Audit-Log zu hinterlassen.

Standard-Schwelle: 10.

Benachrichtigung bei Fehlern

Einzelne Fehlversuche lösen keine E-Mail aus — sie stehen im Audit-Log. Sobald die Auto-Deaktivierung greift, versucht i-Planner, alle Inhaber der Organisation und die Adressen aus dem Abschnitt E-Mail-Benachrichtigung des Webhooks per E-Mail zu informieren. Jede Adresse wird einzeln eingeplant. Bei einem vorübergehenden Mail-Fehler folgen bis zu drei erneute Versuche; in einem seltenen Absturzfall kann deshalb eine Warnung doppelt ankommen. Falls auch die Wiederholungen scheitern, ist die Benachrichtigung nicht garantiert — prüfe deshalb auch das Audit-Log.

Betreff: Webhook „<Name>“ wurde automatisch deaktiviert
Inhalt: Anzahl der aufeinanderfolgenden Fehler, das Ziel (Host der URL) und der letzte Fehler, z. B. HTTP_503 oder TIMEOUT.
Button: „Webhook prüfen“ führt direkt zum Webhook in den Einstellungen.
Häufigkeit: Benachrichtigungen werden derzeit je Webhook innerhalb von 24 Stunden zusammengefasst, auch wenn er in dieser Zeit erneut aktiviert und deaktiviert wird.

Nach der Behebung schaltest du den Webhook unter Stammdaten wieder auf Aktiv. Der Fehlerzähler beginnt dann bei null.

Empfehlungen für Entwickler

Sofort antworten: Sende ein 2xx, bevor du die Daten verarbeitest. Schreibe sie in deine eigene Warteschlange oder Datenbank und arbeite sie im Hintergrund ab. So bleibst du innerhalb des Timeouts und blockierst i-Planner nicht.
Idempotenz: Behandle dieselbe webhook-id als idempotent — wiederholte Aufrufe dürfen also nichts duplizieren. Die ID bleibt bei allen Versuchen derselben Zustellung gleich.
Reihenfolge: i-Planner garantiert keine Reihenfolge zwischen unterschiedlichen Events. Wenn die Reihenfolge wichtig ist, sortiere sie auf deiner Seite nach timestamp.
Wenig zurückschreiben: i-Planner ignoriert den Inhalt deiner Antwort — er wird nur für das Log gespeichert. Halte ihn kurz, damit dein Endpunkt schnell antworten kann.