Events

Welche Daten werden gesendet?

Jede produktive Nachricht enthält den geänderten Datensatz unter payload.data. Die Feldnamen und Werte entsprechen dem jeweiligen Einzelabruf der v3-REST-API. Aktivierte Zusatzinhalte werden dabei berücksichtigt. Der Empfänger muss das Event deshalb nicht erst über eine ID erneut auflösen.

Gehört der geänderte Datensatz zu einem anderen Datensatz, liefert payload.parent zusätzlich dessen kompakte Identifikation. Bei einer geänderten Adresse erkennt der Empfänger dadurch beispielsweise sofort den zugehörigen Kunden. Bei einem Kommentar ist der Parent der Datensatz, an dem der Kommentar tatsächlich hängt – etwa eine Aktivität oder ein Vertrag.

Für Entwickler: Der äußere Aufbau der Nachricht wird als Envelope bezeichnet und ist bei jedem Event gleich:

{
  "request_id": "9a8b7c…",
  "event_name": "addresses.update",
  "timestamp":  "2026-09-07T08:00:00.000Z",
  "payload": {
    "data": {
      "id": 67890,
      "kid": 12345,
      "strasse": "Musterstraße 1",
      "plz": "12345",
      "ort": "Musterstadt",
      "fields": {
        "strasse": { "label": "Straße", "data_type": "string", "select_fields_name": null }
      },
      "select_fields": {}
    },
    "parent": {
      "type": "customer",
      "id": 24680,
      "kid": 12345,
      "anrede": "Herr",
      "titel": "",
      "vorname": "Max",
      "name": "Mustermann"
    }
  }
}

payload.data bleibt immer der Datensatz des ausgelösten Events. payload.parent ist ein direktes Objekt und enthält keine weitere data-Ebene. Es besteht ausschließlich aus type, id, kid, anrede, titel, vorname und name, soweit diese Werte vorhanden sind. type bezeichnet die Art des Parents, zum Beispiel customer, product, user, activity oder contract. Bei Daten ohne auflösbare Zuordnung fehlt parent.

Wenn im Eventbereich Feldbeschreibung aktiviert ist, enthält payload.data zusätzlich fields und select_fields. fields beschreibt die gelieferten Felder mit verständlicher Bezeichnung und Datentyp. Verweist ein Feld über select_fields_name auf eine Auswahlliste, stehen deren Werte unter demselben Namen in select_fields. Bei Kunden, Produktpartnern und Benutzern sind diese Angaben nach Entität gruppiert: beispielsweise payload.data.fields.customers, payload.data.fields.addresses, payload.data.select_fields.customers und payload.data.select_fields.addresses. So bleiben gleichnamige Felder wie art eindeutig. Die Metadaten für eingebettete Adressen stehen einmal bei der Hauptentität, nicht in jeder Adresse. Bei einem eigenständigen Nummern-Event liegt die Beschreibung von art dagegen unter payload.data.fields.art und die zugehörige Auswahlliste unter payload.data.select_fields.nummern – genau wie im v3-Einzelabruf. Hat ein Datensatz keine solchen Metadaten, werden beide Objekte leer als {} gesendet. Bei sehr großen, organisationsabhängigen Listen – Vermittler, Pools und Benutzergruppen – liefert i-Planner nur die Einträge, deren IDs im konkreten Datensatz vorkommen. Ist die Einstellung aus, fehlen fields und select_fields vollständig; die eigentlichen Datenfelder bleiben gleich.

Beispiel für customers.update mit eingebetteten Kontaktdaten und aktivierter Feldbeschreibung (gekürzt):

{
  "event_name": "customers.update",
  "payload": {
    "data": {
      "kid": 12345,
      "name": "Mustermann",
      "contacts": [{ "id": 678, "kid": 12345, "art": "E-Mail", "wert": "max@example.com" }],
      "fields": {
        "customers": {
          "name": { "label": "Name", "data_type": "string", "select_fields_name": null }
        },
        "contacts": {
          "art": { "label": "Medium", "data_type": "string", "select_fields_name": "kommunikationArt" }
        }
      },
      "select_fields": {
        "customers": {},
        "contacts": {
          "kommunikationArt": [{ "value": "E-Mail", "display": "E-Mail" }]
        }
      }
    }
  }
}

Die Entitätsnamen verschachteln nur die Feldinfos, nicht den Kundendatensatz oder seine contacts-Liste. Das optionale REST-Query-Flag flat für Unterressourcen wird bei Webhooks nicht verwendet. Ein contacts.insert ist außerdem ein eigenes Event und wird nicht schon durch „Kontaktdaten mitsenden“ beim Kunden abonniert.

Kann i-Planner den Datensatz oder den erforderlichen übergeordneten Datensatz nicht vollständig zusammenstellen, wird kein unvollständiger Webhook mit data: null gesendet. i-Planner stoppt die Zustellung vorher und protokolliert den Fehler intern.

Die vollständige Nachricht wird bei POST, PUT oder PATCH als Body gesendet. Bei application/x-www-form-urlencoded wird sie entsprechend form-codiert. GET/DELETE sind nicht konfigurierbar, weil die Webhook-Signatur den exakten Body absichert.

Zusätzliche Daten auswählen

Im Bereich Events der Webhook-Einstellungen legst du nicht nur Anlegen, Aktualisieren und Löschen fest. Für viele Datenbereiche kannst du zusätzliche verknüpfte Datensätze aktivieren. Diese werden direkt in payload.data eingebettet. Nicht ausgewählte Inhalte fehlen, damit der Webhook übersichtlich bleibt. Außerdem kannst du pro Eventbereich entscheiden, ob Feldbeschreibungen und Auswahllisten mitgesendet werden. Neu hinzugefügte Eventbereiche starten ohne diese Metadaten; bereits bestehende Eventbereiche behalten ihre bisherige vollständige Payload, bis du die Einstellung änderst. Jeder Eventbereich kann nur einmal hinzugefügt werden; beim Hinzufügen zeigt die Auswahl nur noch freie Bereiche.

Beim Löschen sendet i-Planner den Datensatz unmittelbar vor der Löschung. Ist die Feldbeschreibung für diesen Eventbereich eingeschaltet, enthält auch ein Lösch-Event fields und select_fields in payload.data – genau wie beim Anlegen oder Aktualisieren. Zusätzliche untergeordnete Datensätze wie Adressen oder Vertrags-Tarife werden bei Lösch-Events nicht eingebettet, weil sie nach der Löschung nicht mehr zuverlässig ermittelt werden können.

Wo wurde die Änderung ausgelöst?

Ein Event wie „Kunde angelegt“ kann durch einen Mitarbeiter in i-Planner oder durch ein externes System über die REST-API ausgelöst werden. Pro Webhook entscheidest du, welche dieser Quellen berücksichtigt werden. Sind beide aktiviert, werden beide Arten von Änderungen gesendet.

Verfügbare Events

i-Planner bietet derzeit 64 Events in 23 Datenbereichen. In den Einstellungen wählst du pro Eventbereich Aktionen wie Anlegen, Aktualisieren und Löschen; bei Zuordnungen heißen sie Zuweisen und Entfernen. Links steht der technische Event-Name für dein System, rechts die Bezeichnung aus den Einstellungen und wann das Event gesendet wird.

Kunden

Kunden sind die Stammdaten eines Kunden, Kunden-Beziehungen Verknüpfungen wie Ehepartner, Kind oder Arbeitgeber.

Verträge

Vertrags-Personen sind die versicherten Personen am Vertrag, Vertrags-Tarife die Tarife am Vertrag.

Produktpartner

Produktpartner sind Versicherer, Banken oder Fondsgesellschaften — mit ihren Ansprechpartnern und Anbieter-Portalen.

Schäden, Finanzen, Ziele

Schadensfälle, Finanzeinträge (Einnahmen, Ausgaben, Vermögen, Verbindlichkeiten) sowie Wünsche und Ziele eines Kunden.

Stammdaten (Kontakt, Adresse, Bank, …)

Diese Datensätze können an Kunden und Benutzern hängen: Kontaktdaten (E-Mail und Telefon), Adressen, Bankverbindungen, Nummern (z. B. Steuer- oder Vermittlernummern), Identitätsdaten (z. B. Ausweis und Pass) sowie Beruf und Arbeitgeber. Bei Produktpartnern gibt es davon Adressen, Kontaktdaten, Bankverbindungen und Nummern.

Weitere CRM-Daten

Aktivitäten (Termine, Aufgaben, E-Mails, Anrufe, Notizen), Dokumente, Kommentare, Follower und Tag-Zuweisungen an Datensätzen. Änderungen am Tag-Katalog selbst lösen kein Event aus.

Benutzer

Mitarbeiter-Stammdaten der Organisation.