Webhooks
Was ein Webhook ist, was du dafür brauchst, wie du die Webhook-Liste liest und wie du einen Webhook pausierst, kopierst oder löschst.
Ein Webhook schickt eine HTTP-Anfrage an eine Adresse deiner Wahl, sobald sich in i-Planner etwas ändert. Das passiert zum Beispiel, wenn ein Kunde angelegt oder ein Vertrag aktualisiert wird. So erfährt ein anderes System von der Änderung, ohne dass es regelmäßig nachfragen muss.
Kurz erklärt
Ein Webhook geht in vier Schritten in Betrieb: anlegen, Events auswählen, testen und aktivieren. i-Planner signiert jede Auslieferung. So kann dein Zielsystem prüfen, dass die Anfrage wirklich von i-Planner stammt. Wie viele Webhooks deine Organisation anlegen kann, begrenzt euer Tarif.
Typische Aufgaben unter Organisation › Einstellungen › Entwickler › Webhooks:
- Ein anderes System soll erfahren, wenn ein Kunde angelegt wird: Webhook anlegen und Events auswählen.
- Der neue Webhook soll loslegen: Testen und aktivieren.
- Dein Zielsystem soll prüfen, ob eine Anfrage von i-Planner kommt: Signatur prüfen und Secret verwalten.
- Ein Webhook soll vorübergehend nichts mehr senden: Webhook pausieren, kopieren oder löschen.
- Der Assistant oder eine KI-App soll einen Webhook ansehen, testen oder ändern: Webhooks über den Assistant oder MCP.
Voraussetzungen
- Deine Benutzerrolle braucht Zugriff auf die Einstellungen und in deren Detail-Rechten im Abschnitt Entwickler für das Auswahlfeld Webhooks mindestens Nur lesen. Fehlt der Zugriff, erscheint der Menüpunkt nicht. Mit Nur lesen steht in der Liste statt Bearbeiten der Eintrag Ansehen.
- Zum Anlegen, Ändern, Kopieren, Aktivieren, Deaktivieren, Testen und zum Anzeigen oder Rotieren des Secrets brauchst du Lesen + Bearbeiten, zum Löschen Lesen + Bearbeiten + Löschen. Eine Person mit Administrator-Rolle vergibt das unter Benutzerrollen. Mit Nur lesen sind auf der Seite eines Webhooks alle Felder gesperrt, und Secret anzeigen, Wechseln und Test senden fehlen.
- Eine Zieladresse, die von außen erreichbar ist und mit
https://beginnt. - Wie viele Webhooks deine Organisation anlegen kann, begrenzt euer Tarif. Deaktivierte Webhooks zählen mit.
Die Webhook-Übersicht
Unter Organisation › Einstellungen › Entwickler › Webhooks stehen alle Webhooks deiner Organisation in einer Tabelle mit den Spalten Name, Ziel, Status, Letzter Test und Erstellt am. Mit dem Suchfeld Webhooks filtern... grenzt du die Liste ein, oben rechts wechselst du zwischen Liste und Kacheln. Der Knopf Neuer Webhook legt einen neuen an. Solange noch kein Webhook angelegt ist, steht in der Tabelle Keine Webhooks vorhanden.
Unter Ziel steht die Ziel-URL. Die Methode steht nur davor, wenn sie nicht POST ist. Die Beschreibung erscheint in der Übersicht nicht. Die Spalte Status zeigt, ob der Webhook arbeitet:
| Status | Bedeutung |
|---|---|
| Aktiv (grün) | Aktiv und mit Events verknüpft. Der Webhook arbeitet. |
| Keine Ereignisse (orange) | Aktiv, aber ohne Events. Er wird nie ausgelöst. |
| Inaktiv (rot) | Inaktiv. Das gilt auch für jeden neu angelegten Webhook, bis du ihn aktivierst. |
Die Spalte Letzter Test zeigt das Ergebnis des letzten Tests: Erfolgreich, Fehler oder Nicht getestet. Nicht getestet steht auch wieder, sobald du URL, Methode, Content-Type oder HTTP-Header geändert hast, denn damit verfällt der letzte Test samt seiner Fehlermeldung.
Hat deine Organisation so viele Webhooks, wie euer Tarif erlaubt, bleibt der Knopf Neuer Webhook sichtbar, öffnet aber keine neue Seite mehr. Ein Klick darauf zeigt stattdessen das Fenster Webhook-Kontingent mit dem Text „Der Tarif erlaubt maximal <n> Webhooks. Deaktivierte Webhooks zählen mit. Erst Löschen gibt einen Platz frei. Für weitere ist ein Tarifwechsel nötig.“ Du schließt es mit Verstanden.
Webhook pausieren, kopieren oder löschen
Öffne Organisation › Einstellungen › Entwickler › Webhooks und klicke am rechten Rand der Zeile auf das Drei-Punkte-Menü:
| Aktion | Wirkung |
|---|---|
| Bearbeiten | Öffnet den Webhook zum Ändern. Ohne Bearbeitungsrecht heißt der Eintrag Ansehen. |
| Kopieren | Legt eine Kopie mit dem Namen Kopie von … an und öffnet sie. i-Planner übernimmt URL, Methode, Events, Quellen, Header, die erweiterten Einstellungen und die Adressen unter E-Mail-Benachrichtigung. Das Signing-Secret wird neu erzeugt. Die Kopie ist immer inaktiv. Teste sie und aktiviere sie dann. Sie zählt gegen das Webhook-Kontingent eures Tarifs. |
| Deaktivieren | Erscheint bei einem aktiven Webhook. Der Webhook feuert nicht mehr, bleibt aber erhalten. |
| Aktivieren | Erscheint bei einem inaktiven Webhook. Gelingt nur mit gültigem Test, siehe Webhook aktivieren. |
| Löschen | Entfernt den Webhook endgültig, nach der Rückfrage „Webhook ‚…‘ wirklich löschen? Es werden keine Daten mehr an diese Adresse übermittelt, und die Liste der bisherigen Zustellungen im Audit-Log geht verloren.“ |
Nach der Aktion bestätigt i-Planner mit „Webhook aktiviert“, „Webhook deaktiviert“ oder „Webhook gelöscht“. Eine Kopie öffnet sich gleich. Misslingt eine Aktion, nennt i-Planner den Grund oder meldet etwa „Der Status konnte nicht geändert werden.“
Markierst du mehrere Webhooks über ihre Kästchen, deaktivierst du sie in einem Schritt. Klicke dafür unter der Tabelle auf Deaktivieren und bestätige die Rückfrage. Bereits inaktive Webhooks bleiben unverändert.
Pausieren kannst du auch über den Schalter Aktiv unter Stammdaten. Hast du an URL, Methode, Content-Type und HTTP-Header nichts geändert, schaltest du den Webhook ohne neuen Test wieder ein.
Webhooks über den Assistant oder MCP
Der i-Planner-Assistant und eine über MCP verbundene KI-App wie Claude oder ChatGPT zeigen dir die Webhooks mit ihren Events, ihrem Ziel, dem letzten Test, dem letzten Fehler und den letzten Zustellungen. Das Ziel nennen sie dabei nur mit seinem Host, etwa hooks.example.com, ohne Pfad und Parameter. Das Signatur-Secret zeigen sie nie. Du siehst es nur auf der Seite des Webhooks.
Was mehr Daten nach außen schickt, geht nie über MCP: ein neuer Webhook, ein neues Ziel, zusätzliche Events und das Wiedereinschalten. Das erledigst du im Assistant oder hier auf der Seite.
| Auftrag | Im Assistant | Über MCP |
|---|---|---|
| Webhooks auflisten und ansehen | ja | ja |
| Einen Test senden | voreingestellt per Freigabekarte | ja |
| Deaktivieren | voreingestellt per Freigabekarte | ja |
| Umbenennen, die Beschreibung ändern, Events entfernen | voreingestellt per Freigabekarte | ja |
| Events hinzufügen | voreingestellt per Freigabekarte | nein |
| Einen Webhook anlegen | voreingestellt per Freigabekarte | nein |
| Die Ziel-URL ändern | voreingestellt per Freigabekarte | nein |
| Wieder aktivieren | voreingestellt per Freigabekarte | nein |
| Methode, Content-Type, Header, Quellen, Wiederholungen, E-Mail-Benachrichtigung, Secret, Kopieren und Löschen | nein, nur hier auf der Seite | nein |
Steht das Werkzeug, etwa Webhook ändern, unter Organisation › Einstellungen › KI & Agenten › Werkzeuge in der Spalte Assistant auf Mit Freigabe, wie voreingestellt, speichert der Assistant eine Änderung erst, wenn du die Freigabekarte mit Erlauben bestätigst. Beim Anlegen und beim Ändern des Ziels zeigt die Karte von der neuen Ziel-URL den Host und den Pfad, damit du sie prüfen kannst. Zugangsdaten in der Adresse, die Werte von Parametern und alles hinter # stehen dort als ***, etwa https://hooks.example.com/neu?token=***. Ein bisheriges Ziel zeigt die Karte nur mit dem Host. Ein Ziel mit Zugangsdaten in der Adresse, etwa https://name:passwort@hooks.example.com/neu, stellt i-Planner allerdings nie zu, siehe Der Test scheitert bei Zugangsdaten in der URL. Auf Aktiviert speichert der Assistant ohne Karte. Über MCP führt i-Planner einen erlaubten Auftrag direkt aus. Ob die KI-App vorher nachfragt, entscheidet die App. Soll eine über MCP verbundene KI-App Events hinzufügen, lehnt i-Planner ab: „Über MCP lassen sich Ereignisse nur entfernen. Neue Ereignisse fügst du im Assistant per Karte oder in der Oberfläche hinzu.“
Ein Webhook, den der Assistant anlegt, ist zunächst inaktiv und hat noch kein Signatur-Secret. Er sendet mit der Methode POST im Format application/json, ohne eigene Header, aus allen Quellen und ohne weitere Empfänger unter E-Mail-Benachrichtigung. Das Secret entsteht mit dem ersten Test oder schon vorher, wenn du hier auf der Seite des Webhooks Secret anzeigen wählst. Aktivieren lässt sich der Webhook wie auf der Seite erst nach einem erfolgreichen Test, siehe Webhook aktivieren.
Ein Test über den Assistant oder MCP sendet wie auf der Seite einen als Test gekennzeichneten Beispiel-Datensatz an das aktuelle Ziel. Du erfährst, ob er geklappt hat, den HTTP-Status und die Laufzeit, aber nicht die Antwort deines Zielsystems. Das Ergebnis steht danach auch in der Übersicht in der Spalte Letzter Test, als Erfolgreich oder Fehler, und oben auf der Seite des Webhooks als Letzter Test erfolgreich oder Letzter Test Fehler.
Fehler nennen der Assistant und die KI-App nur mit einem Code und einer festen Beschreibung, beim Test ebenso wie den letzten Fehler des Webhooks, etwa „timeout: Das Ziel hat nicht rechtzeitig geantwortet.“ Den Fehlertext selbst geben sie nie weiter, denn er kann Header-Werte oder die Ziel-URL enthalten. Den vollständigen Text siehst du nur auf der Seite des Webhooks, nach einem Test unter Response.
| Code | Beschreibung |
|---|---|
invalid_header | Ein HTTP-Header des Webhooks ist ungültig, z. B. mit einem Zeilenumbruch im Wert. |
invalid_target | Die Ziel-URL ist ungültig, z. B. mit Zugangsdaten in der Adresse. |
blocked_target | Das Ziel ist nicht erlaubt: nur öffentliche https-Adressen, nie das iPlanner-API. |
changed_during_test | Die Konfiguration wurde während des Tests geändert; bitte erneut testen. |
signing_failed | Die Zustellung konnte nicht signiert werden. |
http_<Status>, etwa http_500 | Das Ziel antwortete mit HTTP <Status>. |
timeout | Das Ziel hat nicht rechtzeitig geantwortet. |
dns | Der Host des Ziels wurde nicht gefunden. |
tls | Die gesicherte Verbindung zum Ziel ist fehlgeschlagen (Zertifikat oder TLS). |
delivery_failed | Die Verbindung zum Ziel ist fehlgeschlagen. |
unknown | Die Zustellung ist fehlgeschlagen; Einzelheiten stehen auf der Seite des Webhooks. |
Änderungen über den Assistant oder MCP stehen wie Änderungen auf der Seite unter Organisation › Audit-Log im Protokoll Einstellungen. Anlegen, Aktivieren, Deaktivieren und ein neues Ziel lösen dieselben Sicherheits-Mails aus, siehe Weitere Empfänger benachrichtigen.
Voraussetzungen:
- Unter Organisation › Einstellungen › KI & Agenten › Werkzeuge stehen die Werkzeuge dafür nicht auf Deaktiviert, in der Spalte Assistant für den Assistant und in der Spalte MCP für MCP. Zum Ansehen sind das Webhooks lesen und Webhook lesen, für Tests und Änderungen Webhook testen, Webhook deaktivieren und Webhook ändern. Webhook anlegen, Webhook-Ziel ändern und Webhook aktivieren gibt es nur im Assistant, in der Spalte MCP steht bei ihnen Nicht verfügbar. Voreingestellt ist keines davon deaktiviert.
- Deine Rolle braucht für Webhooks dieselbe Stufe wie auf dieser Seite: Nur lesen zum Ansehen, Lesen + Bearbeiten für Tests und Änderungen. Einen eigenen Schalter für die Werkzeuge hat die Rolle nicht.
- Für MCP braucht deine Rolle MCP verwenden. Die verbundene KI-App arbeitet mit deinen Rechten, begrenzt durch die KI-Freigaben deiner Organisation, also durch die Spalte MCP unter Werkzeuge. Stellt deine Organisation dort ein Werkzeug später auf Aktiviert, kann die App es nutzen, sofern deine Rolle es erlaubt. Ein neu aktiviertes Werkzeug erscheint in der App, sobald sie ihre Werkzeugliste neu lädt, siehe Eine KI-App zeigt nicht alle Werkzeuge und MCP einrichten.
Häufige Fragen
Unter Organisation › Audit-Log im Protokoll Webhooks. Dort steht jede ausgehende Zustellung mit Zeitpunkt, Trigger, Methode, Ziel, Status, Versuch, Dauer und Request-ID. Über den Filter Status schränkst du die Liste auf Erfolg oder Fehlgeschlagen ein. Manuelle Tests stehen dort nicht. Deren Ergebnis siehst du nur auf der Webhook-Seite selbst. Wie lange die Zustellungen aufbewahrt werden, stellst du unter Organisation › Einstellungen › Organisation › Audit-Log ein.
Bei einem Webhook ist Deaktivieren fast immer der praktischere Weg. Der Eintrag bleibt mit Zieladresse, Events, Headern und Signing-Secret unverändert stehen und feuert nur nicht mehr. Wieder einschalten kannst du ihn im Drei-Punkte-Menü mit Aktivieren oder unter Stammdaten mit dem Schalter Aktiv. Hast du an URL, Methode, Content-Type und Headern nichts geändert, brauchst du dafür keinen neuen Test, und in deinem Zielsystem musst du nichts anfassen. Löschen entfernt den Webhook endgültig und nimmt seine bisherigen Auslieferungen mit. Im Audit-Log ist die Zustellhistorie danach weg und nicht wiederherstellbar. Dafür gibt erst das Löschen einen Platz im Webhook-Kontingent eures Tarifs frei. Solange du die Zustellhistorie noch brauchst oder den Webhook später wieder anschalten willst, deaktiviere ihn.
i-Planner protokolliert jedes Anlegen, Ändern, Kopieren, Deaktivieren, Löschen und jedes Rotieren des Secrets. Nachlesen kannst du es unter Organisation › Audit-Log im Protokoll Einstellungen. In der Spalte Bereich steht dann Webhooks. Die ausgehenden Zustellungen selbst stehen nicht dort, sondern im eigenen Protokoll Webhooks.
Weitere Themen
- Webhook einrichten: anlegen, Events, Quellen, Header, Signatur, Wiederholungen und weitere Empfänger.
- Testen und aktivieren: einen Test senden und den Webhook einschalten.
- Fehlerbehebung: wenn der Webhook nicht feuert, sich nicht aktivieren lässt oder die URL abgelehnt wird.
- API-Tokens: der umgekehrte Weg, bei dem ein anderes Programm i-Planner aufruft.
- Audit-Log: jede ausgehende Zustellung im Protokoll Webhooks.