Fehlerbehebung

Die häufigsten Probleme unter Organisation › Einstellungen › Entwickler › Webhooks, geordnet nach dem, was du beobachtest – jeder Abschnitt nennt die Ursache und den nächsten Schritt.

Wie du einen Webhook einrichtest, testest und aktivierst, steht auf den anderen Seiten unter Webhooks.

Der Menüpunkt „Webhooks“ fehlt

Deiner Benutzerrolle fehlt der Zugriff auf die Einstellungen oder auf den Bereich Entwickler › Webhooks. Eine Person mit Administrator-Rolle kann das unter Organisation › Einstellungen › Team & Rollen › Benutzerrollen freigeben. Zum Ansehen genügt Nur lesen, zum Anlegen und Ändern Lesen + Bearbeiten.

Es lässt sich kein weiterer Webhook anlegen

Euer Tarif begrenzt die Zahl der Webhooks, und das Kontingent ist ausgeschöpft. Ein Klick auf den Knopf Neuer Webhook über der Liste öffnet dann statt einer neuen Seite das Fenster Webhook-Kontingent mit der Obergrenze. Deaktivierte Webhooks zählen mit. Erst Löschen gibt einen Platz frei. Für mehr Webhooks ist ein Tarifwechsel nötig.

Steht im Fenster stattdessen „Das Tarif-Kontingent konnte nicht ermittelt werden. Bitte versuche es später erneut.“, versuche es etwas später noch einmal.

Die URL wird nicht angenommen

Drei Gründe kommen infrage:

Die Adresse beginnt nicht mit https://. http:// reicht nicht.
Sie zeigt auf eine interne Adresse, also localhost oder eine private IP-Adresse. Das Ziel muss aus dem Internet erreichbar sein.
Sie zeigt auf die i-Planner-API selbst (api.i-planner.app oder api.i-planner.de). Das ist als Endlosschleifen-Schutz gesperrt. Ein Schreibzugriff auf die API würde genau das Event auslösen, das der Webhook abonniert hat.

Fehlt https:// oder zeigt die Adresse auf die i-Planner-API, meldet die Maske direkt am Feld URL „URL muss mit https:// beginnen und darf nicht auf das iPlanner-API (api.i-planner.app/.de) zeigen — Endlosschleifen-Schutz.“ Die Adresse wird dann nicht gespeichert. Lehnt i-Planner eine API-Adresse erst beim Speichern ab, erscheint stattdessen das Fenster URL nicht erlaubt.

Der Test scheitert bei Zugangsdaten in der URL

Steht in der URL ein Name oder Passwort vor dem Host, etwa https://name:passwort@hooks.example.com/, stellt i-Planner an dieses Ziel nie zu. Jeder Test schlägt fehl. Auf der Seite steht dann unter Response eine Fehlermeldung, über den Assistant oder MCP heißt der Fehler „invalid_target: Die Ziel-URL ist ungültig, z. B. mit Zugangsdaten in der Adresse.“ Ein inaktiver Webhook lässt sich deshalb nicht aktivieren, und ein aktiver scheitert bei jeder Zustellung. Nimm die Zugangsdaten aus der URL und gib sie als eigenen HTTP-Header mit, etwa als Authorization.

Ein HTTP-Header lässt sich nicht speichern

Name und Wert eines Headers dürfen keinen Zeilenumbruch und kein Nullzeichen enthalten. Sonst lehnt i-Planner das Speichern mit „HTTP-Header dürfen keine Zeilenumbrüche oder Nullzeichen enthalten.“ ab. Trage Name und Wert jeweils in einer Zeile ein.

GET oder DELETE lassen sich als Methode nicht auswählen

Die Signatur unterschreibt den Inhalt des Requests. GET und DELETE haben keinen Body, den man unterschreiben könnte. Zur Auswahl stehen deshalb nur POST, PUT und PATCH.

Bei den Header-Werten steht nur `***`

i-Planner blendet Header-Werte beim Laden der Seite grundsätzlich aus, weil sie Zugangsdaten enthalten können. Der gespeicherte Wert ist unverändert vorhanden und wird weiterhin mitgesendet. Lässt du *** stehen, bleibt er erhalten. Erst wenn du das Feld überschreibst, ersetzt der neue Wert den alten.

Das Signing-Secret ist verloren

Öffne den Webhook über Organisation › Einstellungen › Entwickler › Webhooks und Bearbeiten. Klicke unter HTTP-Signatur auf Secret anzeigen. i-Planner zeigt das aktuelle Signing-Secret erneut an, und du kannst es mit Kopieren übernehmen. Dafür braucht deine Benutzerrolle Lesen + Bearbeiten. Ohne dieses Recht fehlt der Knopf, siehe „Secret anzeigen“ und „Test senden“ fehlen.

„Secret anzeigen“ und „Test senden“ fehlen

Deine Benutzerrolle hat für Webhooks nur die Stufe Nur lesen. Dann öffnet sich ein Webhook unter Organisation › Einstellungen › Entwickler › Webhooks nur zum Ansehen. Alle Felder sind gesperrt. Im Bereich HTTP-Signatur fehlen Secret anzeigen und Wechseln, im Bereich Webhook testen die Auswahl Event und Test senden. Dafür braucht deine Rolle in den Detail-Rechten der Zeile Einstellungen im Abschnitt Entwickler beim Auswahlfeld Webhooks mindestens Lesen + Bearbeiten. Das stellt eine Person ein, die Benutzerrollen bearbeiten darf, unter Organisation › Einstellungen › Team & Rollen › Benutzerrollen.

Der Test bekommt eine Weiterleitung (301/302) zurück

i-Planner folgt Weiterleitungen bewusst nicht. Geprüft und angesprochen wird nur die eingetragene Adresse. Trage die endgültige Ziel-URL direkt unter HTTP › URL ein.

Der Schalter „Aktiv“ lässt sich nicht einschalten

Ein Webhook lässt sich erst aktivieren, wenn für seine aktuelle URL und HTTP-Konfiguration ein erfolgreicher Test gespeichert ist. Bei einem neuen Webhook ist der Schalter außerdem gesperrt, bis Name und URL ausgefüllt sind und der Webhook angelegt ist. Sende im Bereich Webhook testen mit Test senden einen Test. Ist er erfolgreich, kannst du Aktiv unter Stammdaten einschalten. Einzelheiten stehen unter Webhook aktivieren.

Ein Webhook steht auf „Keine Ereignisse“

Steht in der Spalte Status Keine Ereignisse, ist der Webhook aktiv, hat aber keine Events eingerichtet. Deshalb wird er nie ausgelöst. Öffne den Webhook über Organisation › Einstellungen › Entwickler › Webhooks und Bearbeiten. Lege dann im Bereich Events mindestens einen Eventbereich mit einer Aktion an. Wie das geht, steht unter Events auswählen.

Der Webhook feuert nicht

Prüfe der Reihe nach:

Ist der Webhook eingeschaltet? Steht in der Liste unter Organisation › Einstellungen › Entwickler › Webhooks in der Spalte Status Inaktiv, ist er es nicht. Ein neuer Webhook bleibt inaktiv, bis du ihn nach einem erfolgreichen Test unter Stammdaten mit Aktiv einschaltest.
Hat er Events? Ohne eingerichteten Eventbereich passiert nichts. In der Liste steht dann in der Spalte Status Keine Ereignisse.
Welche Quellen sind eingeschaltet? Ist nur REST-API eingeschaltet, lösen Änderungen aus der Oberfläche nichts aus, und umgekehrt.
Sende einen Test (Webhook testen › Test senden), um zu sehen, ob die Adresse überhaupt antwortet.

Der Webhook ist plötzlich inaktiv

Entweder hat die Auto-Deaktivierung gegriffen. Nach der eingestellten Zahl aufeinanderfolgender Fehler schaltet i-Planner den Webhook selbst ab. Du findest die Einstellung unter Erweitert, mit 0 schaltest du sie aus. Oder jemand hat ihn über Deaktivieren oder den Schalter Aktiv pausiert. Dann schickt i-Planner die E-Mail „Webhook deaktiviert“ an diese Person, an alle Inhaber und an die Adressen unter E-Mail-Benachrichtigung.

Weitere Themen

Webhook einrichten: URL, Events, Quellen, Header und Signatur.
Testen und aktivieren: einen Test senden und den Webhook einschalten.
Webhooks: die Webhook-Liste, pausieren, kopieren und löschen.
Entwickler › Fehlerbehebung: wenn API-Aufrufe abgelehnt werden, die Gruppe Entwickler fehlt oder „Dieser Bereich ist derzeit nicht verfügbar oder nicht freigegeben.“ erscheint.
Audit-Log: jede Zustellung im Protokoll Webhooks, filterbar nach Erfolg und Fehlgeschlagen.