Zum Inhalt springen
Kibi Connect
Handbuch Kibi Connect

n8n-Integration: Kibi Connect automatisieren

Aktualisiert am Lesezeit: 5 Min.

Auf dieser Seite

Mit Webhooks meldet deine Plattform Ereignisse wie neue Beiträge oder erledigte Aufgaben in Echtzeit an andere Systeme. n8n ist ein Werkzeug für Workflow-Automatisierung, das du selbst betreiben oder als n8n Cloud nutzen kannst. Mit dem offiziellen Community Node für Kibi Connect verbindest du deine Plattform so mit anderen Systemen, ohne Code zu schreiben.

Info

Webhooks und die REST API schalten System-Admins frei. Webhook-Endpoints in der Administration verwalten ebenfalls nur System-Admins.

Webhooks einrichten#

Ein Webhook-Endpoint ist eine Adresse, an die die Plattform bei den gewählten Ereignissen eine signierte Nachricht schickt.

Öffne Administration → Integrationen → Webhooks.

Stell den Schalter bei Ausgehende Webhooks auf Aktiv. Standardmäßig ist er aus, dann sendet die Plattform nichts.

Seite „Webhooks“ mit dem Schalter „Ausgehende Webhooks“ auf „Inaktiv“ und dem Knopf „Webhook-Endpoint erstellen“

Klick auf Webhook-Endpoint erstellen.

Trag Name und URL ein und wähle unter Abonnierte Ereignisse mindestens ein Ereignis.

Formular „Webhook-Endpoint erstellen“ mit Name, URL und den Ereignissen „Beitrag erstellt“ und „Aufgabe erledigt“

Klick auf Erstellen.

Kopiere das Webhook-Secret sofort und klick auf Fertig. Es wird nur dieses eine Mal angezeigt.

Dialog „Webhook-Secret erstellt“ mit Warnhinweis und verdecktem Secret

Warnung

Die URL muss öffentlich erreichbar sein. Adressen im internen Netz lehnt die Plattform ab: „Bitte eine öffentlich erreichbare Adresse angeben.“ Weiterleitungen werden nicht verfolgt, antworte also direkt an der eingetragenen URL mit einem Erfolgsstatus (2xx). Hast du das Secret verloren, lösch den Endpoint und leg ihn neu an.

Verfügbare Ereignisse#

Du kannst Ereignisse zu diesen Bereichen abonnieren:

  • Benutzer: erstellt, aktualisiert, deaktiviert

  • Beiträge: erstellt, aktualisiert, gelöscht

  • Kalendereinträge: erstellt, aktualisiert, abgesagt, wiederhergestellt

  • Aufgaben: erstellt, aktualisiert, erledigt, zugewiesen, dazu Kommentare, Anhänge und gebuchte Aufgaben-Zeiten

  • Gruppen: erstellt, Mitglied hinzugefügt, Mitglied entfernt

  • Wiki-Seiten: erstellt, aktualisiert, gelöscht

  • Formulare: Formularantwort eingegangen

  • Kontakte: erstellt, aktualisiert, gelöscht

  • Firmen: erstellt, aktualisiert, gelöscht

Info

Die Ereignisse zu Kontakten und Firmen enthalten keine Namen oder Kontaktdaten, nur die Kennungen und die Sichtbarkeit. Die Daten selbst liest dein Empfänger mit einem Token mit der Berechtigung contacts:read nach. Dabei gilt, was die Person sehen darf, der der Token gehört.

Endpoint testen und überwachen#

Die Tabelle zeigt je Endpoint Name, URL, die abonnierten Ereignisse, ob er Aktiv ist, die Zahl der Fehler und wann zuletzt zugestellt wurde. Rechts in jeder Zeile stehen die Aktionen als Symbole: Bearbeiten, Test senden, Deaktivieren und Löschen. Mit Nur fehlerhafte blendest du alle Endpoints ohne Fehler aus.

Tabelle der Webhook-Endpoints mit dem Endpoint „CRM-Anbindung“, der Spalte „Ereignisse“ und den Aktionen

Klick in der Zeile des Endpoints auf Test senden (Papierflieger-Symbol).

Bestätige im Dialog mit Test senden. Die Plattform schickt ein Ereignis test.ping über den echten Zustellweg und meldet Test-Webhook gesendet.

Dialog „Test senden“ mit dem Ereignis test.ping

Klick in der Zeile auf Bearbeiten und öffne den Reiter Zustellprotokoll. Dort siehst du je Zustellung Zeitpunkt, Ereignis, Versuch, Erfolg, Status, Dauer und Fehler. Über das Suchfeld Ereignis findest du die Zustellungen eines bestimmten Ereignisses.

Reiter „Zustellprotokoll“ mit einer erfolgreichen Zustellung von test.ping und dem Status 200
  • Wiederholungen: Schlägt eine Zustellung fehl oder antwortet dein Empfänger nicht innerhalb von 10 Sekunden, versucht es die Plattform insgesamt dreimal.

  • Automatisch deaktiviert: Nach 10 Fehlschlägen in Folge deaktiviert die Plattform den Endpoint und benachrichtigt die System-Admins. Prüf dann die Adresse und schalte den Endpoint wieder ein.

  • Löschen: Löscht den Endpoint samt seinem Zustellprotokoll. Das lässt sich nicht rückgängig machen.

Signatur prüfen#

Jede Zustellung trägt den Header X-Kibi-Signature (HMAC-SHA256). Prüf ihn in deinem Empfänger mit dem Secret und einem Timing-sicheren Vergleich, zum Beispiel hash_equals in PHP oder crypto.timingSafeEqual in Node.js. So stellst du sicher, dass die Nachricht wirklich von deiner Plattform stammt. Den n8n-Trigger musst du dafür nicht anpassen, er prüft die Signatur selbst.

Was ist die n8n-Integration?#

Paket: @weslink/n8n-nodes-kibi-connect, MIT-Lizenz, verfügbar auf npm. Quelle und vollständige Referenz (Englisch): GitHub-Repository.

Das Paket enthält zwei Nodes:

  • Kibi Connect (Aktions-Node): 18 Ressourcen mit insgesamt 129 Operationen, die die REST API abdecken: Beiträge, Wiki-Seiten, Aufgaben, Termine, Chat, Gruppen, Benachrichtigungen, Umfragen, Suche, Besprechungslinks, Dateien und Ordner, Freigabelinks, Dokumente (DMS), Medien-Upload, Zeiterfassung und Nutzendenverzeichnis.

  • Kibi Connect Trigger: Startet einen Workflow, sobald die Plattform ein Webhook-Ereignis liefert, zum Beispiel einen neuen Beitrag oder eine erledigte Aufgabe.

Warnung

Für die Ressource Document muss das Modul Dokumentenmanagement installiert sein, für Time Tracking das Modul Zeiterfassung. Ist das Modul nicht installiert, antwortet die Plattform auf den betroffenen Routen mit 404, bewusst genauso wie bei einer unbekannten ID.

n8n einrichten#

Die Karte n8n unter Integrationen → Übersicht zeigt, ob alles bereit ist. Solange die REST API aus ist, steht dort Nicht eingerichtet und Benötigt die REST-API. Einrichten führt direkt zur richtigen Seite, Anleitung zum npm-Paket.

Karte „n8n“ mit dem Status „Nicht eingerichtet“ und dem Hinweis „Benötigt die REST-API“

1. REST API freischalten#

Öffne Administration → Integrationen → API.

Schalte REST API aktivieren ein und klick auf Speichern.

Einstellungen der REST API mit dem eingeschalteten Schalter „REST API aktivieren“

Auf derselben Seite kannst du mit IP-Einschränkung aktivieren die Adressen begrenzen und mit Token-Erstellung auf bestimmte Rollen einschränken festlegen, wer Token anlegen darf. Mehr dazu steht auf der Seite Kibi API.

2. Token anlegen#

Öffne dein Profil und den Reiter Integrationen.

Klick im Abschnitt API auf Neuen Token erstellen.

Trag einen Name ein und hake unter Berechtigungen die Scopes an, die deine Operationen brauchen. Für den automatischen Trigger sind das webhooks:read und webhooks:write.

Trag eine Integrations-Kennung ein, zum Beispiel n8n. Der Node nennt dieses Feld Integration Slug.

Klick auf Token erstellen und kopiere das Token.

Token-Formular mit den Berechtigungen webhooks:read und webhooks:write und der Integrations-Kennung n8n

Info

Token und Integrations-Kennung lassen sich nachträglich nicht ändern. Fehlt später eine Berechtigung, braucht es ein neues Token. Ein Token handelt immer als die Person, der es gehört.

3. Community Node installieren#

Öffne in n8n Settings → Community Nodes → Install und gib den Paketnamen @weslink/n8n-nodes-kibi-connect ein.

Leg im Node die Zugangsdaten Kibi Connect API an: Base URL (die Adresse deiner Plattform, ohne Schrägstrich am Ende und ohne /api), API Token und Integration Slug.

Der Verbindungstest im Dialog bestätigt die Einrichtung.

Der Trigger: zwei Betriebsarten#

Automatisch (Standard)#

Beim Aktivieren des Workflows legt der Node den Webhook-Endpoint auf deiner Plattform selbst an, beim Deaktivieren entfernt er ihn wieder. Der Endpoint erscheint auch in der Tabelle unter Webhooks. Das setzt voraus:

  • Der Schalter Ausgehende Webhooks steht auf Aktiv.

  • Das Token hat die Berechtigungen webhooks:read und webhooks:write.

  • Das Token hat eine Integrations-Kennung.

  • Das Token gehört einer Person mit der Rolle System Admin.

Manuell#

Schalte im Node Register Webhook Automatically aus, wenn das Token diese Voraussetzungen nicht erfüllt oder die Administration die Endpoints selbst verwalten will:

Kopiere die Webhook-URL des Nodes aus dem n8n-Editor.

Leg damit unter Webhooks einen Endpoint an, wie oben beschrieben.

Trag das einmalig angezeigte Secret im Node ins Feld Webhook Secret ein.

Signaturprüfung#

Jede Zustellung wird per HMAC-SHA256 gegen den Header X-Kibi-Signature geprüft. Eine Zustellung ohne gültige Signatur beantwortet der Node mit 401 und startet den Workflow nicht.

Endlosschleifen vermeiden#

Warnung

Ein Workflow, der die Plattform liest und schreibt, würde sich sonst endlos selbst auslösen. Jede Webhook-Nachricht trägt data.origin. Darin steht, ob die Änderung über die API (source: api) oder durch eine Person beziehungsweise einen Hintergrundprozess (source: ui) ausgelöst wurde, und welche Integrations-Kennung dahintersteckt.

Die Option Ignore Own Writes im Trigger ist deshalb standardmäßig aktiviert und verwirft Zustellungen mit der eigenen Kennung. Das hat zwei Folgen:

  • Ein Token ohne Integrations-Kennung kann nichts als eigene Änderung erkennen. Die Option wirkt dann nicht.

  • Zwei Workflows mit derselben Kennung ignorieren auch die Änderungen des jeweils anderen. Gib jeder Integration eine eigene Kennung, wenn du das nicht willst.

Beispiel-Workflows#

Zwei Beispiel-Workflows liegen im GitHub-Repository unter examples/ und lassen sich in n8n über Workflow → Import from File laden:

  • Feed-Ankündigung im Chat (announce-new-posts-in-chat.json): Kündigt neue Beiträge automatisch in einem Chat an.

  • Rechnungs-Ablage aus dem Postfach (file-invoices-from-email-into-the-dms.json): Legt PDF-Rechnungen aus einem E-Mail-Postfach im Dokumentenmanagement ab und benachrichtigt anschließend die Buchhaltung per Chat-Nachricht.

Verfügbarkeit#

Das Paket liegt auf npm und lässt sich in selbst gehosteten n8n-Instanzen sofort installieren. Die Paketdokumentation nennt dieselbe Installation auch für n8n Cloud. Bietet deine n8n-Cloud-Instanz das Paket nicht an, nutze eine selbst gehostete Instanz oder Webhooks mit einem eigenen Empfänger.