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.
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.
- 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. Die Zeile über der Liste zeigt, wie viele es sind. Rechts daneben legt der +-Knopf einen neuen an. Sein Hinweistext lautet Neuer Webhook. Solange noch kein Webhook angelegt ist, steht dort 0 Webhooks.
Sobald Webhooks vorhanden sind, steht jeder in einer eigenen Zeile, oben der Name und darunter die Ziel-URL. Die Methode steht nur davor, wenn sie nicht POST ist. Die Beschreibung erscheint in der Übersicht nicht. Links vor dem Namen sitzt ein farbiger Punkt:
| Punkt | Bedeutung |
|---|---|
| Grün | Aktiv und mit Events verknüpft. Der Webhook arbeitet. |
| Gelb | Aktiv, aber ohne Events. Er wird nie ausgelöst. |
| Rot | Inaktiv. Das gilt auch für jeden neu angelegten Webhook, bis du ihn aktivierst. |
Rechts steht ein Kennzeichen zum letzten Test: Letzter Test erfolgreich oder Letzter Test Fehler. Ob ein Webhook aktiv ist, erkennst du nur am Punkt.
Hat deine Organisation so viele Webhooks, wie euer Tarif erlaubt, bleibt der +-Knopf 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 „Aktiviert“, „Deaktiviert“, „Kopiert“ oder „Gelöscht“. Misslingt sie, erscheint etwa „Fehler beim Aktivieren“.
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.
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.