Einrichten
Mit einem Webhook informiert i-Planner ein anderes System automatisch über Änderungen — zum Beispiel über einen neuen Kunden oder einen geänderten Vertrag. Auf dieser Seite erfährst du, was du dafür einrichten musst.
Zuletzt geprüft: 15. September 2026
Kurz erklärt
Ein Webhook ist eine automatische Nachricht von i-Planner an eine von dir hinterlegte Internetadresse. Sobald ein ausgewähltes Event eintritt, sendet i-Planner die passenden Daten an dein System.
Typische Einsätze im Maklerbüro:
- Neuer Kunde angelegt — Willkommens-E-Mail oder Maklervollmacht automatisch aus deinem E-Mail- oder Dokumenten-Tool verschicken.
- Vertrag angelegt oder geändert — Bestand in Courtage-Abrechnung, Buchhaltung oder Vergleichsrechner ohne Doppelerfassung aktuell halten.
- Schaden gemeldet — Vorgang im Service-Desk eröffnen und das Team im Chat informieren.
- Adresse oder Bankverbindung geändert — Änderung an Versicherer-Portale oder das Kundenportal weitergeben.
Du bestimmst für jeden Webhook:
- welche Änderungen gemeldet werden,
- ob Änderungen aus der Benutzeroberfläche, der REST-API oder aus beiden Quellen berücksichtigt werden,
- an welche HTTPS-Adresse die Daten gehen,
- welche zusätzlichen Daten mitgesendet werden,
- und wie i-Planner bei einem Fehler reagieren soll.
In i-Planner einrichten
Webhooks werden pro Organisation unter Einstellungen → Webhooks angelegt. Das Formular enthält folgende Bereiche — in dieser Reihenfolge:
Stammdaten- Name, Beschreibung und Aktiv-Schalter. Neue Webhooks bleiben zunächst inaktiv; der Schalter wird nach einem erfolgreichen Test freigegeben.
HTTP- Methode (POST/PUT/PATCH), Ziel-URL (muss mit
https://beginnen), Content-Type und eine Verzögerung von 1–10 Sekunden vor dem ersten Versuch. HTTP-Header- Eigene HTTP-Header, die bei jedem Aufruf mitgesendet werden — z. B.
Authorizationoder ein API-Key. Details unter Eigene HTTP-Header. HTTP-Signatur- Ein geheimer Schlüssel, mit dem dein System prüfen kann, ob eine Nachricht wirklich von i-Planner stammt. Technische Anleitung unter Sicherheit.
Quellen- Lege fest, ob Änderungen aus der Benutzeroberfläche (User Interface), der REST-API oder aus beiden Bereichen berücksichtigt werden. Details unter Events.
Events- Wähle pro Eventbereich die gewünschten Aktionen, beispielsweise „Kunde anlegen“ oder „Vertrag aktualisieren“. Hier legst du auch zusätzliche Inhalte des Payloads fest. Vollständige Liste unter Events.
Erweitert- Timeout (10–60 s), Wiederholungen (0–10 ×), Pause zwischen Versuchen (Retry-Backoff, 0–600 s) und Auto-Deaktivierung nach mehreren Fehlern. Details unter Zustellung.
E-Mail-Benachrichtigung- Der Inhaber wird bei Problemen immer informiert. Optional kannst du weitere E-Mail-Adressen hinterlegen.
Webhook testen- Einmaliger Test-Aufruf an die konfigurierte URL — direkt aus den Einstellungen. Details unter Testen.
Schnellstart für Entwickler
In fünf Schritten zum ersten Webhook.
1. Empfänger vorbereiten. Stelle einen öffentlich erreichbaren HTTPS-Endpunkt bereit, der JSON annimmt, die Signatur prüft und schnell mit einem 2xx-Status antwortet. Fertige Prüf-Funktionen für Node.js, Python und PHP findest du unter Signatur prüfen, einen minimalen Empfänger zum Mitschreiben unter Lokal testen.
2. Webhook in i-Planner anlegen. Einstellungen → Webhooks → Neuer Webhook. Name vergeben, URL aus Schritt 1 eintragen, HTTPS prüfen. Der neue Webhook bleibt zunächst inaktiv.
3. Quellen und Events wählen. Aktiviere mindestens eine Quelle und ein Event, damit der Webhook gesendet werden kann.
4. Testen. Wähle im Abschnitt Webhook testen ein Event aus und sende einen Test. Du siehst den gesendeten Aufruf, die Antwort und die Antwortzeit direkt unter dem Formular. Nur ein erfolgreicher Test (2xx) gibt den Aktiv-Schalter frei. Details und Fehlerdiagnose stehen unter Testen.
5. Aktivieren. Stelle den Schalter unter Stammdaten auf Aktiv. Erst dann können die ausgewählten Events produktiv gesendet werden. Ein Test allein schaltet einen bewusst pausierten Webhook nicht wieder ein.
Häufige Fragen
Prüfe in dieser Reihenfolge: War der Test erfolgreich und steht der Webhook unter Stammdaten auf Aktiv? Ist mindestens eine Quelle und ein Event ausgewählt? Beginnt die URL mit https:// und ist sie öffentlich erreichbar? Danach hilft ein Test aus den Einstellungen — Aufruf und Antwort siehst du direkt unter dem Formular.
Bei 5xx, 408/429, Timeout oder Netzwerkfehler so oft, wie unter Erweitert eingestellt — standardmäßig 3-mal im Abstand von 60 Sekunden. Andere Antworten mit 4xx werden nicht wiederholt. Details unter Automatische Wiederholungen.
Ja. Bei Wiederholungen kann eine Nachricht doppelt eintreffen. Der Header webhook-id bleibt dabei gleich, damit dein System Duplikate erkennt. Die Zustellung wird erst nach erfolgreicher Prüfung von Limit, Einstellungen und Daten eingeplant; eine tatsächliche Ankunft ist nicht garantiert. Siehe Zustellung.
Nicht garantiert. Wiederholungen und Netzwerklaufzeiten können die Reihenfolge verändern. Sortiere bei Bedarf nach dem Feld timestamp im Body.
Nach der unter Erweitert eingestellten Zahl aufeinanderfolgender Fehler — standardmäßig 10 — schaltet i-Planner den Webhook ab und versucht, die hinterlegten Empfänger per E-Mail zu informieren. Nach der Behebung schaltest du ihn unter Stammdaten wieder auf Aktiv. Siehe Auto-Deaktivierung.
Aus den Einstellungen derzeit nicht. Welche Zustellung fehlgeschlagen ist und warum, siehst du im Audit-Log.
Über die Signatur-Header, die jeder Aufruf trägt. Prüfe sie mit dem Secret aus dem Abschnitt HTTP-Signatur — Beispiele für Node.js, Python und PHP unter Signatur prüfen.
Nein, i-Planner erreicht nur öffentliche HTTPS-Adressen. Für die Entwicklung nutzt du einen Tunnel wie ngrok, siehe Lokal testen.
Weitere Themen
- Events — Aufbau der gesendeten Daten, zusätzliche Inhalte, Quellen und alle 64 Events.
- Testen — Test-Aufruf aus i-Planner, gesendete Daten, Antwort und häufige Fehler.
- Zustellung — Erfolgreiche und fehlgeschlagene Zustellungen, automatische Wiederholungen und Timeouts.
- Sicherheit — Sichere Ziel-Adressen, Signaturprüfung und Wechsel des geheimen Schlüssels.