n8n-Automatisierung für Sparks (Entwickler)

Sprache: Deutsch | English

Dieses Handbuch richtet sich an Entwickler und Integratoren, die n8n (self-hosted oder Cloud) mit Sparks verbinden. Es beschreibt Auth, REST-Oberflächen, Webhooks, Beispiel-Workflows, Custom Nodes und Betriebshinweise.

Kurzüberblick im App-Repo: Vistameet-Teams/docs/N8N.md · OpenAPI: Vistameet-Teams/docs/openapi/sparks-automation-v1.yaml.

1. Überblick

Sparks bietet mehrere Integrationswege. Für n8n sind die wichtigsten:

Richtung	Mechanismus	Typische Use Cases
n8n → Sparks Chat	Incoming Webhook → Matrix-Raum	Alerts aus GitHub, Jira, Monitoring, CRM
n8n → Kalender / Tasks / Chat	REST `/api/v1/automation` mit API-Key `spk_…`	Termine/Aufgaben anlegen, Nachrichten senden
Sparks → n8n	Outgoing Event Webhooks (Account-UI)	Meeting angelegt/beendet, Webinar-Registrierung
Sparks → n8n (Call-Lifecycle)	Env `CONF_CALL_LOG_WEBHOOK_URL`	Join / Room-Ende → CRM, Digest
Optional	Custom Nodes `n8n-nodes-sparks`	Kalender, Tasks, Chat ohne manuelle HTTP-Nodes

┌─────────────┐     spk_ Key / Webhook      ┌──────────────────┐
│    n8n      │ ──────────────────────────► │ Sparks Node API  │
│  Workflows  │ ◄────────────────────────── │ + Matrix Bot     │
└─────────────┘   Event / Call-Log POST     └──────────────────┘

Nicht für n8n gedacht: LiveKit-Mediensteuerung, Matrix-E2EE-Crypto-Bootstrap, Sygnal-Push-Registration.

2. Voraussetzungen

2.1 Sparks-Seite

Erreichbare API-Base-URL (z. B. https://api.example.com oder lokaler Node-Server)
Account mit Möglichkeit, API-Keys zu erzeugen: Account → KI-Zugriff / MCP
Für Chat-Schreiben über Automation-REST: Scope matrix und serverseitig MATRIX_JWT_SECRET (wie beim MCP)
Für Incoming Webhooks (Bot → Raum): MATRIX_WEBHOOK_ACCESS_TOKEN (oder MATRIX_BOT_ACCESS_TOKEN), MATRIX_HOMESERVER_URL, WEBHOOK_MAPPINGS
Datenbank-Migrationen aktuell (Tabelle automation_webhook_subscriptions für Outgoing Events)

2.2 n8n-Seite

n8n mit HTTP Request- und Webhook-Nodes (Standard)
Optional: Custom-Extension-Pfad für n8n-nodes-sparks (self-hosted)
Netzwerk: n8n muss Sparks erreichen; Sparks muss n8n-Webhook-URLs erreichen (für Trigger)

3. Authentifizierung und Scopes

3.1 API-Key `spk_…` (empfohlen für REST)

Account öffnen → KI-Zugriff / MCP (/mcp)
Key erzeugen, Scopes wählen (Opt-in)
Klartext einmalig speichern

Header (eine Variante genügt):

Authorization: Bearer spk_…

oder

X-Sparks-Api-Key: spk_…

Gültig für:

Endpoint	Zweck
`/api/mcp`	MCP Streamable HTTP (KI-Clients)
`/api/v1/automation/*`	REST für n8n
`/v1.0/me/calendar/events`, `/v1.0/me/tasks`, `/v1.0/me/chats/…`	Graph-ähnliche Aliase

Scopes (Auswahl):

Scope	REST-Relevanz
`calendar`	Termine lesen/anlegen
`tasks`	Aufgaben lesen/anlegen
`matrix`	Räume listen, Nachrichten senden (plaintext-fähig)
`calls`	vor allem MCP: Anrufliste, Call-Details, Meeting-Transkripte (`list_calls`, `get_call`, `get_call_transcript`)
`memory` / `contacts` / `files` / `activity`	vor allem MCP-Tools

Keys rotieren und widerrufen über dieselbe Account-Seite. Keine LiveKit-/Transcriber-Service-Tokens an n8n geben.

3.2 Incoming Webhook-ID

Der Pfadparameter webhookId ist das Geheimnis. Mapping Raum ↔ ID über Env WEBHOOK_MAPPINGS (kein User-API-Key).

3.3 Keycloak Bearer

Account-/Appointment-REST (/api/account, /api/local-appointments, …) verlangt OIDC. Für n8n unpraktisch (Token-Refresh). Bevorzugen Sie spk_… + Automation-API.

4. Quick Wins

4.1 n8n → Matrix-Chat (Incoming Webhook)

Endpoints (identisch):

POST /webhooks/incoming/:webhookId (kanonisch)
POST /api/webhooks/incoming/:webhookId (Alias)

Body:

{
  "text": "Deployment erfolgreich"
}

Alternativ: message, body oder content.

Server-Env (Beispiel):

MATRIX_WEBHOOK_ACCESS_TOKEN=syt_…
MATRIX_HOMESERVER_URL=https://matrix.example.com
WEBHOOK_MAPPINGS={"n8n":"!roomId:matrix.example.com","github":"!other:matrix.example.com"}
# optional: WEBHOOK_ROOM_ID=!room:…  → webhookId "default"

n8n: HTTP Request Node → Method POST → URL https://<api>/webhooks/incoming/n8n → JSON Body.

Der Bot muss Mitglied des Zielraums sein. Details: App-Repo docs/INCOMING_WEBHOOKS.md.

4.2 Call-Lifecycle → n8n

Auf dem Sparks-Node-Server:

CONF_CALL_LOG_WEBHOOK_URL=https://<n8n-host>/webhook/sparks-call
CONF_CALL_LOG_WEBHOOK_SECRET=optional-bearer
# CONF_CALL_LOG_NOTIFY_PARTICIPATION_START=false

Payloads u. a. kind=participation_start und kind=livekit_room_session_ended. Vertrag: App-Repo docs/CONF_TEAM_CALLLOG_S2S_DELIVERABLES.md.

In n8n: Webhook-Trigger mit passendem Path; optional Header Authorization: Bearer … prüfen.

5. Automation REST API

Base: {API_BASE}/api/v1/automation
Auth: spk_… + Scope
OpenAPI: App-Repo docs/openapi/sparks-automation-v1.yaml

5.1 Endpoints

Method	Path	Scope	Beschreibung
`GET`	`/calendar/events?start=&end=`	`calendar`	Termine im Zeitraum (ISO-8601)
`POST`	`/calendar/events`	`calendar`	Termin anlegen
`GET`	`/tasks`	`tasks`	Aufgaben listen
`POST`	`/tasks`	`tasks`	Aufgabe anlegen
`GET`	`/chats/rooms`	`matrix`	Beigetretene Matrix-Räume
`POST`	`/chats/rooms/:roomId/messages`	`matrix`	Textnachricht senden

Graph-Aliase (gleiche Handler):

GET/POST /v1.0/me/calendar/events
GET/POST /v1.0/me/tasks
GET /v1.0/me/chats/rooms
POST /v1.0/me/chats/rooms/:roomId/messages

5.2 Beispiele

Termin anlegen

curl -sS -X POST "$API_BASE/api/v1/automation/calendar/events" \
  -H "Authorization: Bearer $SPK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Standup",
    "start": "2026-08-01T09:00:00.000Z",
    "end": "2026-08-01T09:15:00.000Z",
    "timeZone": "Europe/Berlin"
  }'

Aufgabe anlegen

curl -sS -X POST "$API_BASE/api/v1/automation/tasks" \
  -H "Authorization: Bearer $SPK_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Follow-up aus n8n", "priority": 5 }'

Nachricht in Matrix-Raum

curl -sS -X POST "$API_BASE/api/v1/automation/chats/rooms/!abc:example.com/messages" \
  -H "Authorization: Bearer $SPK_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Hallo aus n8n" }'

5.3 Typische Fehlercodes

HTTP	Bedeutung
`401`	Key fehlt / ungültig / widerrufen
`403`	Scope fehlt (`MCP_SCOPE_MISSING`)
`400`	Validierung (z. B. fehlendes `subject`)
`503`	DB/Kalender deaktiviert oder Matrix-Session nicht verfügbar

6. Outgoing Event Webhooks (Trigger für n8n)

6.1 Konfiguration

UI: Account → Automatisierung (/automation)

HTTPS-URL (lokal: http://localhost… erlaubt)
Events wählen
Optional Secret → Header X-Sparks-Signature: sha256=<hmac>

REST (Keycloak Bearer, Account-API):

Method	Path
`GET` / `POST`	`/api/account/me/automation-webhooks`
`PATCH` / `DELETE`	`/api/account/me/automation-webhooks/:id`

6.2 Events

Event	Wann	Empfänger-Logik
`meeting.created`	Lokaler Termin angelegt	Organizer (`creatorKeycloakSub`)
`meeting.ended`	LiveKit-Raum beendet	Creator, wenn Room-Name = Appointment-ID
`registration.created`	Webinar-Registrierung	Creator + Webinar-Write-Permissions

6.3 Delivery-Payload

POST <ihre-n8n-url>
Content-Type: application/json
User-Agent: Sparks-Automation-Webhook/1.0
X-Sparks-Event: meeting.created
X-Sparks-Delivery: evt_…
X-Sparks-Signature: sha256=…   # nur wenn Secret gesetzt

{
  "id": "evt_a1b2c3…",
  "type": "meeting.created",
  "createdAt": "2026-07-30T12:00:00.000Z",
  "data": {
    "appointmentId": "…",
    "subject": "Standup",
    "startTime": "…",
    "endTime": "…",
    "matrixRoom": "!…:example.com",
    "meetingType": null
  }
}

Timeout serverseitig ca. 10 s. Letzter Fehler / letzte Zustellung in der Account-UI sichtbar.

6.4 HMAC prüfen (n8n / Middleware)

Signatur = HMAC-SHA256 über den rohen Request-Body mit dem konfigurierten Secret, Hex, Prefix sha256=.

7. Beispiel-Workflows in n8n

7.1 Alert → Matrix

Trigger (GitHub / Cron / anderer Webhook)
Set / Code: Text aus Payload bauen
HTTP Request → POST …/webhooks/incoming/<id> mit { "text": "…" }

7.2 Meeting beendet → Notion / CRM

Account → Automatisierung: Event meeting.ended, URL = n8n Webhook
n8n Webhook → IF type === meeting.ended → Notion/CRM/HTTP

7.3 Ticket → Kalendertermin

Trigger aus Ticketsystem
HTTP Request POST /api/v1/automation/calendar/events mit spk_… (Scope calendar)
Optional: Raum-Nachricht mit Join-Hinweis (matrix-Scope oder Incoming Webhook)

7.4 Webinar-Registrierung → Slack/Teams

Event registration.created an n8n Webhook
Nachricht an externes Channel-System formatieren

8. Custom Nodes (`n8n-nodes-sparks`)

Im App-Repo: Ordner n8n-nodes-sparks/.

Komponente	Inhalt
Credential Sparks API	Base URL + `spk_…`
Node Sparks	Calendar list/create, Task list/create, Chat list rooms / send message

Installation (self-hosted, Skizze):

cd ../Vistameet-Teams/n8n-nodes-sparks
npm install
npm run build
export N8N_CUSTOM_EXTENSIONS=/absoluter/pfad/zu/n8n-nodes-sparks
# n8n neu starten

Trigger-Events bleiben über die Account-UI + n8n-Webhook-Node (kein eigener Trigger-Node nötig).

9. Betrieb und Umgebungsvariablen

Variable	Zweck
`MATRIX_WEBHOOK_ACCESS_TOKEN` / `MATRIX_BOT_ACCESS_TOKEN`	Bot für Incoming Webhooks
`MATRIX_HOMESERVER_URL`	Homeserver
`WEBHOOK_MAPPINGS`	JSON `webhookId → roomId`
`WEBHOOK_ROOM_ID`	Raum für `webhookId=default`
`CONF_CALL_LOG_WEBHOOK_URL`	Outbound Call-Lifecycle → n8n
`CONF_CALL_LOG_WEBHOOK_SECRET`	Optional Bearer
`MATRIX_JWT_SECRET`	Matrix-Session für Automation/MCP Chat
`DATABASE_URL`	Pflicht für Keys und Outgoing Webhooks
`SPARKS_DB_CALENDAR`	`0` deaktiviert DB-Kalender (REST liefert 503)

Migration Outgoing Webhooks: automation_webhook_subscriptions (Prisma). Lokal bei Drift: npx prisma migrate deploy (nicht zwingend migrate reset).

10. Sicherheit

Scopes minimal halten; Keys wie Passwörter behandeln
Incoming webhookId = Secret (kein HMAC derzeit) → lange zufällige IDs, URLs nicht loggen
Outgoing: Secret setzen und Signatur in n8n prüfen
E2EE: Automation/MCP lesen keine verschlüsselten Matrix-Inhalte; Schreiben nur über plaintext-fähige Sessions
Keine Admin-Graph-Keys (ADMIN_GRAPH_API_KEY) oder LiveKit-Service-Tokens in n8n
Tenant-Gates für MCP/n8n können betrieblich noch eingeschränkt werden (Roadmap)

Verwandt: End-to-End-Verschlüsselung – Entscheidungshilfe, Account – KI-Zugriff / MCP.

11. Troubleshooting

Symptom	Prüfung
`401` auf Automation	Key korrekt? Prefix `spk_`? Widerrufen?
`403` / `MCP_SCOPE_MISSING`	Passenden Scope am Key setzen
Incoming `404 Webhook not found`	`WEBHOOK_MAPPINGS` / `default` + `WEBHOOK_ROOM_ID`
Incoming `503`	Bot-Token + Homeserver-Env
Incoming `502`	Bot nicht im Raum / Matrix-Fehler
Chat REST `503`	`MATRIX_JWT_SECRET`, Localpart-Mapping, User hat Matrix-Identität
Kein `meeting.ended`	LiveKit-Webhooks aktiv? Room-Name = Appointment-ID? Subscription enabled?
Outgoing timeout / `lastError`	n8n erreichbar von Sparks-Server? TLS?

12. Quellcode und weiterführende Docs (App-Repo)

Pfad in Vistameet-Teams	Inhalt
`docs/N8N.md`	Kurzübersicht
`docs/INCOMING_WEBHOOKS.md`	Incoming → Matrix
`docs/openapi/sparks-automation-v1.yaml`	OpenAPI 3.0
`docs/API.md`	Endpoint-Katalog
`server/routes/automation-api.ts`	REST-Handler
`server/lib/automation-webhooks.ts`	Outgoing Delivery
`server/routes/webhook-incoming.ts`	Incoming
`n8n-nodes-sparks/`	Community Nodes
`account/src/pages/AutomationWebhooksPage.tsx`	Account-UI

1. Überblick​

2. Voraussetzungen​

2.1 Sparks-Seite​

2.2 n8n-Seite​

3. Authentifizierung und Scopes​

3.1 API-Key spk_… (empfohlen für REST)​

3.2 Incoming Webhook-ID​

3.3 Keycloak Bearer​

4. Quick Wins​

4.1 n8n → Matrix-Chat (Incoming Webhook)​

4.2 Call-Lifecycle → n8n​

5. Automation REST API​

5.1 Endpoints​

5.2 Beispiele​

5.3 Typische Fehlercodes​

6. Outgoing Event Webhooks (Trigger für n8n)​

6.1 Konfiguration​

6.2 Events​

6.3 Delivery-Payload​

6.4 HMAC prüfen (n8n / Middleware)​

7. Beispiel-Workflows in n8n​

7.1 Alert → Matrix​

7.2 Meeting beendet → Notion / CRM​

7.3 Ticket → Kalendertermin​

7.4 Webinar-Registrierung → Slack/Teams​

8. Custom Nodes (n8n-nodes-sparks)​

9. Betrieb und Umgebungsvariablen​

10. Sicherheit​

11. Troubleshooting​

12. Quellcode und weiterführende Docs (App-Repo)​

Verwandte Seiten​