Webhook einrichten
Wie du einen Webhook anlegst, seine Events und Quellen auswählst, eigene HTTP-Header und die Signatur einrichtest, Wiederholungen festlegst und weitere Empfänger der Sicherheits-Mails einträgst.
Auf der Seite eines Webhooks unter Organisation › Einstellungen › Entwickler › Webhooks legst du fest, wohin i-Planner sendet, bei welchen Änderungen und mit welchen Daten. Wie du den eingerichteten Webhook anschließend testest und einschaltest, steht unter Testen und aktivieren.
Kurz erklärt
i-Planner legt einen Webhook an, sobald Name und URL ausgefüllt sind. Er ist dann noch inaktiv. Ohne Events wird er nie ausgelöst. Jede Auslieferung wird signiert. Einen Schalter zum Abschalten der Signatur gibt es nicht.
Typische Aufgaben auf der Seite eines Webhooks:
- Ein neuer Webhook soll angelegt werden: Webhook anlegen.
- Nur bestimmte Änderungen sollen gemeldet werden, etwa neue Kunden: Events auswählen.
- Dein Zielsystem erwartet einen API-Schlüssel im Header: Eigene HTTP-Header mitgeben.
- Das Secret soll ausgetauscht werden: Signatur prüfen und Secret verwalten.
- Eine weitere Person soll von Änderungen am Webhook erfahren: Weitere Empfänger benachrichtigen.
Webhook anlegen
Ein Webhook geht in vier Schritten in Betrieb: anlegen, Events auswählen, testen und aktivieren. Das Anlegen geht so:
- Öffne Organisation › Einstellungen › Entwickler › Webhooks.
- Klicke rechts in der Zeile über der Liste auf +. Die Seite Neuer Webhook öffnet sich.
- Unter Stammdaten findest du:
- Aktiv: das oberste Feld. Bei einem neuen Webhook ist der Schalter aus und gesperrt, bis der Webhook angelegt ist. Einschalten kannst du ihn erst nach einem erfolgreichen Test, siehe Webhook aktivieren.
- Name: Pflichtfeld. Er wird in der Übersicht und im Audit-Log angezeigt.
- Beschreibung: optional, wofür der Webhook eingesetzt wird.
- Fülle unter HTTP aus:
- Methode: POST, PUT oder PATCH. Voreingestellt ist POST.
- URL: Pflichtfeld. Die Adresse muss mit
https://beginnen. - Content-Type: application/json (voreingestellt), application/x-www-form-urlencoded oder text/plain.
- Verzögerung: Wartezeit vor dem ersten Request, 1 bis 10 Sekunden. Voreingestellt ist 1 Sekunde.
- Lege im Bereich Events fest, bei welchen Änderungen i-Planner senden soll. Ohne Events wird der Webhook nie ausgelöst.
- Sende im Bereich Webhook testen einen Test und schalte danach unter Stammdaten den Schalter Aktiv ein.
Die Seite hat von oben nach unten die Bereiche Stammdaten, HTTP, HTTP-Header, HTTP-Signatur, Quellen, Events, Erweitert, E-Mail-Benachrichtigung (weitere Empfänger der Sicherheits-Mails) und Webhook testen.
Wie überall im Bereich Organisation gibt es keinen Speichern-Knopf. Jede Änderung wird sofort gespeichert (siehe Speichern geschieht automatisch). Den Webhook selbst legt i-Planner aber erst an, wenn Name und URL beide ausgefüllt sind. Bis dahin merkt sich die Maske deine Eingaben nur. Der neu angelegte Webhook ist inaktiv.
Würde der neue Webhook das Kontingent eures Tarifs überschreiten, erscheint das Fenster Tarif-Kontingent erreicht.
Events auswählen
Unter Events legst du fest, bei welchen Änderungen der Webhook gesendet wird und welche zusätzlichen Daten er enthält.
- Öffne den Webhook über Organisation › Einstellungen › Entwickler › Webhooks und Bearbeiten.
- Klicke im Bereich Events auf +.
- Wähle unter Eventbereich den Datenbereich aus. Zur Auswahl stehen Kunden, Kunden-Beziehungen, Schäden, Finanzen, Ziele, Verträge, Vertrags-Personen, Vertrags-Tarife, Produktpartner, Produktpartner – Ansprechpartner, Produktpartner – Portale, Kontaktdaten, Adressen, Bankverbindungen, Nummern, Identitätsdaten, Beruf & Arbeitgeber, Aktivitäten, Dokumente, Kommentare, Follower, Tags und Benutzer.
- Schalte die Aktionen ein, bei denen i-Planner senden soll. Jeder Schalter trägt die Bezeichnung des Bereichs. Im Bereich Kunden heißen sie Kunde anlegen, Kunde aktualisieren und Kunde löschen. Anlegen, Aktualisieren und Löschen gibt es in den meisten Bereichen. Abweichend davon haben Kunden-Beziehungen, Vertrags-Tarife, Follower und Tags nur Zuweisen und Entfernen (etwa Follower zuweisen und Follower entfernen). Vertrags-Personen haben Zuweisen, Aktualisieren und Entfernen. Kommentare haben nur Anlegen und Löschen.
- Schalte darunter optional zusätzliche Daten zu, die mitgesendet werden sollen. Ohne diese Schalter geht nur der Basisdatensatz raus.
| Zusatzdaten | In welchen Bereichen | Voreinstellung |
|---|---|---|
| Feldbeschreibung mit technischen Erläuterungen zu den einzelnen Datenfeldern und Auswahllisten | alle | ein |
| Adressen, Kontaktdaten, Bankverbindungen, Nummern | Kunden, Produktpartner, Benutzer | aus |
| Beruf & Arbeitgeber, Identitätsdaten | Kunden, Benutzer | aus |
| Vertrags-Personen, Vertrags-Tarife | Verträge | aus |
Jeder Eventbereich darf nur einmal vorkommen. Bereits benutzte Bereiche verschwinden aus der Auswahlliste der übrigen Zeilen. Pro Bereich muss mindestens eine Aktion eingeschaltet sein. Fehlt eine Aktion oder kommt ein Bereich doppelt vor, steht unter Events in Rot „Wähle für jeden Eventbereich mindestens eine Aktion und verwende jeden Bereich nur einmal. Diese Änderung ist noch nicht gespeichert.“ Beim Speichern lehnt i-Planner einen Bereich ohne Aktion mit dem Hinweis „Wähle für ‚…‘ mindestens ein Event aus“ ab. Eine Zeile ohne Bereich lehnt i-Planner mit „Eventbereich ist erforderlich.“ ab.
Beim Löschen eines Datensatzes sendet i-Planner den zuvor erfassten Basisdatensatz.
Quellen einschränken
Öffne den Webhook über Organisation › Einstellungen › Entwickler › Webhooks und Bearbeiten. Unter Quellen legst du fest, wessen Änderungen der Webhook überhaupt sehen soll. Beide Schalter sind bei einem neuen Webhook eingeschaltet:
| Quelle | Bedeutung |
|---|---|
| User Interface | Mitarbeiter haben Daten direkt in der Benutzeroberfläche von i-Planner geändert, zum Beispiel einen Kunden manuell angelegt |
| REST-API | Ein externes System oder Skript hat Daten über die REST-API geändert |
Mindestens eine Quelle muss eingeschaltet bleiben. Schaltest du beide aus, erscheint das Fenster Mindestens eine Quelle erforderlich mit dem Text „Wähle mindestens eine Quelle aus. Zum Pausieren deaktiviere den Webhook.“ Die Änderung wird dann nicht gespeichert. Willst du den Webhook vorübergehend anhalten, nutze den Schalter Aktiv oder im Listenmenü Deaktivieren.
Eigene HTTP-Header mitgeben
Unter HTTP-Header hinterlegst du feste Header, die i-Planner bei jedem Request mitschickt. Das kann zum Beispiel ein Authorization-Header sein oder ein API-Schlüssel, den dein Zielsystem erwartet.
- Öffne den Webhook über Organisation › Einstellungen › Entwickler › Webhooks und Bearbeiten.
- Klicke im Bereich HTTP-Header auf +.
- Trage Name und Wert ein. Beide Felder sind Pflicht. Eine leere Zeile musst du entweder ausfüllen oder wieder entfernen.
Zum Ändern oder Entfernen eines Headers wählst du im Menü am rechten Rand der Zeile Bearbeiten oder Löschen.
Öffnest du die Seite später erneut, steht bei jedem Header-Wert nur noch ***. Der echte Wert bleibt gespeichert und wird weiterhin mitgesendet. i-Planner zeigt ihn nur nicht mehr an. Solange du *** stehen lässt, bleibt der gespeicherte Wert unverändert.
Änderst du einen Header, gilt der letzte erfolgreiche Test nicht mehr. Vor dem nächsten Aktivieren musst du den Webhook erneut testen, siehe Webhook aktivieren.
Signatur prüfen und Secret verwalten
i-Planner signiert jede Auslieferung. Einen Schalter zum Abschalten gibt es nicht. Mit der Signatur kann dein Zielsystem prüfen, ob die Anfrage wirklich von i-Planner stammt und unterwegs nicht verändert wurde. Dafür bekommt jeder Request die Header webhook-id, webhook-timestamp und webhook-signature nach dem Standard-Webhooks-Format.
Öffne den Webhook über Organisation › Einstellungen › Entwickler › Webhooks und Bearbeiten. Im Bereich HTTP-Signatur stehen zwei Schaltflächen:
| Schaltfläche | Wirkung |
|---|---|
| Secret anzeigen | Zeigt das aktuelle Secret an. Über Kopieren landet es in der Zwischenablage, über Ausblenden verschwindet es wieder. |
| Wechseln | Erzeugt ein neues Secret (Meldung Secret gewechselt). Das bisherige bleibt 24 Stunden gültig. |
Das Secret entsteht automatisch beim ersten Speichern des Webhooks. Behandle es wie ein Passwort.
In den 24 Stunden nach dem Rotieren trägt jede Auslieferung beide Signaturen, die mit dem neuen und die mit dem alten Secret. So kannst du dein Zielsystem umstellen, ohne dass in der Zwischenzeit Auslieferungen abgewiesen werden. Wann das alte Secret abläuft, steht nach dem Rotieren unter dem angezeigten Secret.
Wiederholungen und Auto-Deaktivierung
Öffne den Webhook über Organisation › Einstellungen › Entwickler › Webhooks und Bearbeiten. Der Bereich Erweitert steuert, was bei Fehlern passiert:
| Einstellung | Bedeutung | Bereich | Voreinstellung |
|---|---|---|---|
| Timeout | Abbruchzeit für den Request | 10 bis 60 s | 10 s |
| Wiederholungen | Anzahl Wiederholungen bei 5xx oder Netzwerkfehler | 0 bis 10 × | 3 × |
| Retry-Backoff | Pause zwischen den Versuchen | 0 bis 600 s | 60 s |
| Auto-Deaktivierung | Nach wie vielen aufeinanderfolgenden Fehlern der Webhook automatisch deaktiviert wird. 0 schaltet die Auto-Deaktivierung aus. | 0 bis 10 × | 10 × |
Weitere Empfänger benachrichtigen
Ändert jemand einen Webhook, informiert i-Planner per E-Mail diese Person und alle Inhaber der Organisation. Im Bereich E-Mail-Benachrichtigung trägst du zusätzliche Empfänger ein.
- Öffne den Webhook über Organisation › Einstellungen › Entwickler › Webhooks und Bearbeiten.
- Klicke im Bereich E-Mail-Benachrichtigung auf +.
- Trage unter E-Mail-Adresse die Adresse ein. Sie erhält technische Hinweise zusätzlich zum Inhaber.
Ist noch niemand eingetragen, steht dort „Der Inhaber wird bereits informiert. Noch keine weiteren Empfänger hinterlegt.“ Eine Zeile änderst du über Bearbeiten und löschst sie über Entfernen. Die Liste wird als Ganzes automatisch gespeichert. Doppelte Adressen fasst i-Planner zusammen und gleicht Groß- und Kleinschreibung an. Eine ungültige Adresse lehnt i-Planner mit „Bitte eine gültige E-Mail-Adresse eingeben.“ ab.
Die Adressen erhalten dieselben Sicherheits-Mails wie die Inhaber: „Webhook angelegt“ (auch beim Kopieren), „Webhook aktiviert“, „Webhook deaktiviert“, „Webhook gelöscht“ und „Webhook-Ziel geändert“. Jede Mail enthält den Knopf Webhook prüfen, nach dem Löschen Webhooks prüfen.
Häufige Fragen
Nein. Jeder Eventbereich darf pro Webhook nur einmal vorkommen. Bereits benutzte Bereiche stehen in den übrigen Zeilen nicht mehr zur Auswahl. Brauchst du unterschiedliche Zusatzdaten für denselben Bereich, lege über Kopieren einen zweiten Webhook an.
Weil über einen Webhook Daten deiner Organisation nach außen gehen. Beim Anlegen, Kopieren, Aktivieren, Deaktivieren und Löschen und bei einer geänderten Ziel-URL schickt i-Planner eine Sicherheits-Mail. Beispiele sind „Webhook angelegt“ oder „Webhook-Ziel geändert“ mit dem alten und dem neuen Ziel. Sie geht an dich, an alle Inhaber der Organisation und an die Adressen, die beim Webhook unter E-Mail-Benachrichtigung eingetragen sind. Mehrere Änderungen der Ziel-URL kurz hintereinander fasst i-Planner in einer Mail zusammen.
Weitere Themen
- Testen und aktivieren: den eingerichteten Webhook testen und einschalten.
- Fehlerbehebung: wenn die URL nicht angenommen wird, nur
***in den Headern steht oder das Secret verloren ist. - Webhooks: die Webhook-Liste, pausieren, kopieren und löschen.
- Audit-Log-Einstellungen: wie lange die Zustellungen aufbewahrt werden.