# 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 {#kurz-erklaert}

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](/organisation/einstellungen/entwickler/webhooks/einrichten#webhook-anlegen) und [Events auswählen](/organisation/einstellungen/entwickler/webhooks/einrichten#events-auswaehlen).
- Der neue Webhook soll loslegen: [Testen und aktivieren](/organisation/einstellungen/entwickler/webhooks/testen-und-aktivieren).
- Dein Zielsystem soll prüfen, ob eine Anfrage von i-Planner kommt: [Signatur prüfen und Secret verwalten](/organisation/einstellungen/entwickler/webhooks/einrichten#signatur-pruefen-secret-verwalten).
- Ein Webhook soll vorübergehend nichts mehr senden: [Webhook pausieren, kopieren oder löschen](/organisation/einstellungen/entwickler/webhooks/uebersicht#webhook-pausieren-kopieren-loeschen).

## Voraussetzungen {#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](/organisation/einstellungen/team-und-rollen/benutzerrollen/uebersicht).
- 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 {#webhook-uebersicht}

*Animation: Die Seite Webhooks unter Organisation › Einstellungen › Entwickler mit der Zeile „3 Webhooks“ und dem Plus-Knopf. Der Mauszeiger zeigt nacheinander auf die Punkte der drei Webhooks: grün bei „CRM-Abgleich“ (aktiv, mit Events), gelb bei „Buchhaltung“ (aktiv, ohne Events, mit der Methode PUT vor der Ziel-URL) und rot bei „Newsletter-Anmeldung“ (inaktiv), dann auf dessen Kennzeichen „Letzter Test Fehler“; die beiden anderen tragen „Letzter Test erfolgreich“. Am Plus-Knopf erscheint der Hinweis „Neuer Webhook“. Das Drei-Punkte-Menü von „CRM-Abgleich“ bietet Bearbeiten, Kopieren, Deaktivieren und Löschen, das von „Newsletter-Anmeldung“ Aktivieren statt Deaktivieren.*

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 {#webhook-pausieren-kopieren-loeschen}

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

::callout
---
color: amber
icon: i-heroicons-exclamation-triangle
---
Löschen lässt sich nicht rückgängig machen. Mit dem Webhook verschwindet auch seine Zustellhistorie im Audit-Log. Erst das Löschen gibt einen Platz im Webhook-Kontingent frei. Ein deaktivierter Webhook zählt weiter mit.
::

## Häufige Fragen {#haeufige-fragen}

::faq
  :::faq-item{question="Wo sehe ich, ob eine Auslieferung angekommen ist?"}
  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.
  :::

  :::faq-item{question="Ein Webhook wird nicht mehr gebraucht — deaktivieren oder löschen?"}
  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.
  :::

  :::faq-item{question="Wer hat einen Webhook angelegt oder geändert?"}
  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 {#weitere-themen}

- [Webhook einrichten](/organisation/einstellungen/entwickler/webhooks/einrichten): anlegen, Events, Quellen, Header, Signatur, Wiederholungen und weitere Empfänger.
- [Testen und aktivieren](/organisation/einstellungen/entwickler/webhooks/testen-und-aktivieren): einen Test senden und den Webhook einschalten.
- [Fehlerbehebung](/organisation/einstellungen/entwickler/webhooks/fehlerbehebung): wenn der Webhook nicht feuert, sich nicht aktivieren lässt oder die URL abgelehnt wird.
- [API-Tokens](/organisation/einstellungen/entwickler/api-tokens): der umgekehrte Weg, bei dem ein anderes Programm i-Planner aufruft.
- [Audit-Log](/organisation/audit-log): jede ausgehende Zustellung im Protokoll **Webhooks**.