n8n-Workflows

AI-Corporate kann n8n-Workflows über einen Production-Webhook starten. Dies ist nützlich, wenn du außerhalb von AI-Corporate einen automatisierten Prozess starten möchtest, zum Beispiel eine Aufgabe erstellen, einen CRM-Eintrag aktualisieren, einen Reporting-Flow starten oder Formularinformationen an ein anderes System weiterleiten.

Beispiel: Newsartikel auf der Unternehmenswebsite

Angenommen, die Organisation hat einen n8n-Workflow erstellt, der einen Newsartikel auf der WordPress-Website des Unternehmens veröffentlicht. In AI-Corporate gibst du dann nur einen kurzen Textabschnitt ein, zum Beispiel ein paar Sätze über eine Kundenfallstudie, eine Veranstaltung oder einen internen Meilenstein. Mit diesem Text startest du den Workflow in n8n.

Der n8n-Workflow kann danach zum Beispiel:

1. Aus dem kurzen Text einen fertigen Konzepttext erstellen lassen mit einem LLM-Knoten und einer Prompt, die zum Ton des Unternehmens passt.
2. Eine passende Illustration erstellen lassen mit einem zweiten LLM-Knoten, zum Beispiel in den Markenfarben und in einem erkennbaren illustrativen Stil.
3. Den Text und das Bild als Blogbeitrag vorbereiten oder auf der WordPress-Website veröffentlichen.

So arbeiten AI-Corporate und n8n zusammen: In AI-Corporate wählt der Benutzer den Workflow aus und füllt die benötigten Informationen ein. n8n führt danach die automatisierten Schritte aus und sorgt dafür, dass der Newsartikel ordnungsgemäß auf der Website erscheint.

Was macht diese Integration?

Du startest einen n8n-Workflow aus der Workflow-Übersicht. Nur der Production-Webhook, POST und Header-Auth sind verpflichtend. Felder und Rückmeldungen aus n8n sind optional und können unabhängig voneinander eingerichtet werden.

• Hat der Workflow keine Felder, wird der Webhook sofort aufgerufen.
• Hat der Workflow Felder, öffnet sich zuerst ein Formular. Der Benutzer füllt die Felder aus und startet danach den Workflow mit der Schaltfläche.
• Die ausgefüllten Werte werden als JSON im POST-Request an den n8n-Webhook mitgesendet.
• Ohne Rückmeldungen bestätigt AI-Corporate nur, dass der Workflow gestartet wurde und weiterläuft in n8n. Das Fenster zeigt keinen Spinner und kann sofort geschlossen werden.
• Wenn dies bei der Registrierung aktiviert ist, kann der Workflow Zwischensteps oder das Ende zurücksenden an AI-Corporate.
• Wenn die Freigabe bei der Registrierung aktiviert ist, kann der Benutzer eine Wahl direkt in AI-Corporate treffen. n8n fährt danach ab dem wartenden Schritt fort.

n8n-Workflow in AI-Corporate erstellen

Ein Administrator registriert den Workflow wie folgt:

1. Gehe zu Assistenten.
2. Öffne Workflows.
3. Wähle Neue n8n-Workflow.
4. Gib den Namen des Workflows und die n8n-Produktions-URL ein.
5. Stelle Header Authentication mit einem Header-Namen und einem geheimen Header-Wert ein.
6. Wähle unter Rückmeldungen aus n8n nur die Teile aus, die in diesem n8n-Workflow wirklich gebaut wurden: Fortschritt, Freigabe und/oder das Ende des Workflows.
7. Füge gegebenenfalls die Felder hinzu, die im POST-Request mitgesendet werden sollen.
8. Speichere den Workflow.

Alle drei Rückmeldungsoptionen sind standardmäßig ausgeschaltet. Wenn du später Callbacks oder einen Freigabeschritt in n8n hinzufügst, aktualisiere auch die Registrierung in AI-Corporate. Der Dialog weiß dann, ob er nur eine Startbestätigung anzeigen soll oder auf weitere Signale warten muss.

Felder

• Felder sind optional.
• Jedes Feld hat einen Feldnamen und einen Typ.
• Unterstützte Feldtypen sind Kurztext, Langtext, Zahl, Ja/Nein, Datum, eine Auswahl und mehrere Auswahlmöglichkeiten.
• Bei Eine Auswahl und Mehrere Auswahlmöglichkeiten fügt man die verfügbaren Optionen hinzu. Eine Auswahl wird als kompakte Auswahlliste angezeigt; Mehrere Auswahlmöglichkeiten zeigt Kontrollkästchen. Der gewählte Wert bzw. die Werte werden im JSON-Body mitgesendet.
• Pflichtfelder müssen ausgefüllt werden, bevor der Workflow gestartet werden kann.
• Der Feldname wird zum Schlüssel im JSON-Body, der an n8n gesendet wird.

Kompatibler Workflow in n8n erstellen

1. Erstelle in n8n einen neuen Workflow.
2. Füge als ersten Knoten einen Webhook hinzu.
3. Gib diesem Knoten genau den Namen Start workflow. Die untenstehenden Beispielausdrücke verwenden diesen Namen.
4. Setze HTTP Method auf POST.
5. Wähle Authentication: Header Auth und verwende denselben Header-Namen und denselben geheimen Wert wie in AI-Corporate.
6. Setze Respond bzw. Response Mode auf Immediately.
7. Kopiere die Production URL in das Feld n8n production URL in AI-Corporate. Verwende nicht die Test-URL mit /webhook-test/.
8. Aktiviere den Workflow.

Die empfangenen Daten stehen unter body; die technischen Integrationsdaten unter body.integration. Entferne diese nicht in einem Edit Fields-, Set- oder Code-Knoten.

Beispiel der JSON-Body

Wenn du Felder definierst mit den Namen prompt, kundename, zielgruppen und datum, erhält n8n beispielsweise diese JSON-Body. AI-Corporate fügt das integration-Objekt automatisch hinzu.

{
  "prompt": "Erstelle eine kurze Zusammenfassung der Anfrage.",
  "kundename": "Beispielorganisation",
  "zielgruppen": ["mitarbeiter", "kunden"],
  "datum": "2026-09-22",
  "integration": {
    "runId": "chat-dokument-id",
    "tenant": "default",
    "callbackUrl": "https://europe-west1-ai-corporate.cloudfunctions.net/n8nWorkflowCallback",
    "callbackToken": "vorübergehendes-token-für-diese-Ausführung"
  }
}

Das Callback-Token gehört zu einer einzigen Ausführung. Nicht in Logs, festen Konfigurationen oder anderen Systemen speichern.

Optional: Fortschritt und Abschluss zurückmelden

AI-Corporate kann nur anzeigen, was n8n zurückmeldet. Verwende diese Callbacks nur, wenn du in der Registrierung Zwischenfortschritt melden und/oder Ende des Workflows melden aktiviert hast.

Stell jeden Callback-Knoten wie folgt ein:

1. Wähle Method: POST.

2. Klicke bei URL auf Expression und füge ein:

   {{ $('Start workflow').first().json.body.integration.callbackUrl }}

3. Wähle Authentication: None.

4. Aktiviere Send Headers und füge untenstehende Headers hinzu.

5. Aktiviere Send Body und wähle Body Content Type: JSON und Specify Body: Using JSON.

Verwende diese Headers:

Authorization: Bearer {{ $('Start workflow').first().json.body.integration.callbackToken }}
Content-Type: application/json

Sende beispielsweise diese Nachricht, wenn ein Schritt startet:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "document-erstellung-started",
  "type": "progress",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "document_erstellen",
    "label": "Dokument erstellen"
  },
  "message": "Das Dokument wird erstellt."
}

• Verwende für jedes Ereignis innerhalb derselben Ausführung eine eindeutige eventId.
• Verwende einen klaren deutschen step.label; dieser Text wird in der App angezeigt.
• Hast du Ende des Workflows melden aktiviert, sende am Ende immer type: "completed", type: "failed" oder type: "rejected".
• Falls abgeschlossen, ggf. ein output-Objekt mit dem Ergebnis hinzufügen.
• Bei failed eine verständliche Fehlermeldung mitgeben. Die Ausführung stoppt dann auch in der App.

Optional: Freigabe-Anfrage in der App

Verwende einen n8n Wait-Knoten mit On Webhook Call, wenn der Workflow erst nach einer Entscheidung fortfahren darf. Sende vor dem Wait-Knoten einen Callback mit type: "approval_required":

Stelle den Wait-Knoten auf Resume: On Webhook Call, HTTP Method: POST und Authentication: Header Auth ein. Wähle dieselbe Header-Auth-Credential wie bei Start workflow. Füge nach dem Wait-Knoten einen Switch-Knoten hinzu und prüfe darin {{ $json.body.decision }}.

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "controle-dokument",
  "type": "approval_required",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "controle_dokument",
    "label": "Dokument prüfen"
  },
  "approval": {
    "question": "Soll der Workflow fortfahren?",
    "context": "Überprüfen Sie zunächst das generierte Dokument.",
    "resumeUrl": "{{ $execution.resumeUrl }}",
    "choices": [
      { "value": "approve", "label": "Freigeben" },
      { "value": "reject", "label": "Ablehnen" }
    ]
  }
}

Der Benutzer sieht die Optionen im Ausführungsfenster. Nach einer Wahl erhält der Wait-Knoten unter anderem decision. Verwende danach z. B. einen Switch-Knoten, um die passende Fortsetzung zu bestimmen.

Eine Auswahllage darf nur Buchstaben, Zahlen, _ und - enthalten. Das Label darf normale lesbare Texte enthalten.

Produktions-Callback-URL einstellen

Die Produktions-Callback-URL für AI-Corporate ist:

https://europe-west1-ai-corporate.cloudfunctions.net/n8nWorkflowCallback

Kopiere diese URL nicht als festen Text in jede Callback-Knoten. Wähle im URL-Feld des HTTP Request-Knotens Expression und verwende:

{{ $('Start workflow').first().json.body.integration.callbackUrl }}

AI-Corporate liefert damit bei jedem Start automatisch die richtige Produktions-URL. Die feste URL oben verwendest du, um während der Tests zu prüfen, ob der Ausdruck auf AI-Corporate verweist und nicht auf AI-School oder AI-Public.

Die Callables triggerCustomN8nWorkflow, triggerN8nWorkflow und resumeN8nWorkflow werden von der App selbst aufgerufen. Diese URLs musst du nicht in n8n konfigurieren.

Fehler behandeln

Sende erwartete Fehler zurück mit einem Callback des Typs failed. Erstelle zusätzlich einen zentralen Error-Workflow für unerwartete Knotfehler:

1. Erstelle einen neuen Workflow mit einem Error Trigger-Knoten.

2. Füge anschließend einen HTTP Request-Knoten mit Method: POST hinzu.

3. Trage bei URL diese feste Produktions-URL ein:

   https://europe-west1-ai-corporate.cloudfunctions.net/n8nWorkflowExecutionFailed

4. Wähle Authentication: None und füge den Header n8n-handihow-name mit dem geheimen Standardwert des Plattformverwalters hinzu.

5. Wähle einen JSON-Body und füge ein:

{
  "executionId": "{{ $json.execution.id }}",
  "workflowId": "{{ $json.workflow.id }}",
  "workflowName": "{{ $json.workflow.name }}",
  "lastNode": "{{ $json.execution.lastNodeExecuted }}",
  "message": "{{ $json.execution.error.message }}"
}

6. Aktiviere den Error-Workflow.
7. Öffne die Einstellungen des normalen Workflows und wähle diesen bei Error Workflow aus.

Sende direkt nach Start workflow mindestens einen Callback mit executionId: "{{ $execution.id }}". Nur dann kann AI-Corporate einen unerwarteten Fehler der richtigen Ausführung zuordnen.

Wichtige Einschränkungen

• Nur Webhook-Trigger werden unterstützt.
• Nur Production-Webhook-URLs werden unterstützt.
• Test-Webhook-URLs mit /webhook-test/ werden abgelehnt.
• Nur POST wird unterstützt.
• Nur generische Header-Authentifizierung wird unterstützt.
• Der Header-Wert wird in der Anwendung als Geheimnis behandelt.
• Callback-Tokens und Resume-URLs werden nur serverseitig verarbeitet und sind nicht direkt für Benutzer verfügbar.
• Die Tenant-Werte werden serverseitig aus dem eingeloggten Benutzer bestimmt, nicht aus einem Wert, den der Browser mitsendet.

Probleme beheben

• 404 oder Webhook nicht registriert: Aktiviere den Workflow in n8n und verwende die Production-URL.
• Authentifizierungsfehler: Prüfe, ob Header-Name und Wert in beiden Systemen exakt übereinstimmen.
• Fehlende Daten: Prüfe, ob die Feldnamen in der Anwendung den Keys entsprechen, die n8n erwartet.
• Keine Anforderung in n8n: Prüfe, ob der Workflow mit einem Webhook-Trigger beginnt und POST verwendet.
• Ausführungsfenster bleibt aktiv: Hast du Ende des Workflows melden aktiviert, prüfe dann, ob n8n einen letzten completed, failed oder rejected Callback sendet. Wenn du keine Rückmeldungen erwartest, schalte alle drei Optionen bei der Registrierung aus.
• Keine Fortschrittsanzeige sichtbar: Prüfe, ob Zwischenfortschritt melden bei der Registrierung aktiviert ist, oder ob das integration-Objekt erhalten bleibt und ob jeder Callback eine eindeutige eventId hat.
• Freigabe-Schaltflächen funktionieren nicht: Prüfe den Wait-Knoten, resumeUrl, Header-Authentifizierung und die zulässigen Zeichen in choices[].value.