# 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](/organisation/einstellungen/entwickler/webhooks/testen-und-aktivieren).

## Kurz erklärt {#kurz-erklaert}

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](/organisation/einstellungen/entwickler/webhooks/einrichten#webhook-anlegen).
- Nur bestimmte Änderungen sollen gemeldet werden, etwa neue Kunden: [Events auswählen](/organisation/einstellungen/entwickler/webhooks/einrichten#events-auswaehlen).
- Dein Zielsystem erwartet einen API-Schlüssel im Header: [Eigene HTTP-Header mitgeben](/organisation/einstellungen/entwickler/webhooks/einrichten#eigene-http-header-mitgeben).
- Das Secret soll ausgetauscht werden: [Signatur prüfen und Secret verwalten](/organisation/einstellungen/entwickler/webhooks/einrichten#signatur-pruefen-secret-verwalten).
- Eine weitere Person soll von Änderungen am Webhook erfahren: [Weitere Empfänger benachrichtigen](/organisation/einstellungen/entwickler/webhooks/einrichten#weitere-empfaenger-benachrichtigen).

## Webhook anlegen {#webhook-anlegen}

Ein Webhook geht in vier Schritten in Betrieb: anlegen, Events auswählen, testen und aktivieren. Das Anlegen geht so:

1. Öffne **Organisation › Einstellungen › Entwickler › Webhooks**.
2. Klicke rechts in der Zeile über der Liste auf **+**. Die Seite **Neuer Webhook** öffnet sich.
3. 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](/organisation/einstellungen/entwickler/webhooks/testen-und-aktivieren#webhook-aktivieren).
   - **Name**: Pflichtfeld. Er wird in der Übersicht und im Audit-Log angezeigt.
   - **Beschreibung**: optional, wofür der Webhook eingesetzt wird.
4. 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.
5. Lege im Bereich **Events** fest, bei welchen Änderungen i-Planner senden soll. Ohne Events wird der Webhook nie ausgelöst.
6. 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](/organisation/uebersicht#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 {#events-auswaehlen}

Unter **Events** legst du fest, bei welchen Änderungen der Webhook gesendet wird und welche zusätzlichen Daten er enthält.

1. Öffne den Webhook über **Organisation › Einstellungen › Entwickler › Webhooks** und **Bearbeiten**.
2. Klicke im Bereich **Events** auf **+**.
3. 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.
4. 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.
5. 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 {#quellen-einschraenken}

Ö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 {#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.

1. Öffne den Webhook über **Organisation › Einstellungen › Entwickler › Webhooks** und **Bearbeiten**.
2. Klicke im Bereich **HTTP-Header** auf **+**.
3. 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](/organisation/einstellungen/entwickler/webhooks/testen-und-aktivieren#webhook-aktivieren).

## Signatur prüfen und Secret verwalten {#signatur-pruefen-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 {#wiederholungen-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 {#weitere-empfaenger-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.

1. Öffne den Webhook über **Organisation › Einstellungen › Entwickler › Webhooks** und **Bearbeiten**.
2. Klicke im Bereich **E-Mail-Benachrichtigung** auf **+**.
3. 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 {#haeufige-fragen}

::faq
  :::faq-item{question="Kann ich denselben Eventbereich zweimal anlegen?"}
  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.
  :::

  :::faq-item{question="Warum bekommt jemand eine E-Mail, wenn ich einen Webhook anlege oder die Ziel-URL ändere?"}
  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 {#weitere-themen}

- [Testen und aktivieren](/organisation/einstellungen/entwickler/webhooks/testen-und-aktivieren): den eingerichteten Webhook testen und einschalten.
- [Fehlerbehebung](/organisation/einstellungen/entwickler/webhooks/fehlerbehebung): wenn die URL nicht angenommen wird, nur `***` in den Headern steht oder das Secret verloren ist.
- [Webhooks](/organisation/einstellungen/entwickler/webhooks/uebersicht): die Webhook-Liste, pausieren, kopieren und löschen.
- [Audit-Log-Einstellungen](/organisation/einstellungen/organisation/audit-log): wie lange die Zustellungen aufbewahrt werden.