n8n-Workflows

AI-School kann n8n-Workflows über einen Produktions-Webhook starten. Das ist nützlich, wenn du außerhalb von AI-School einen automatisierten Prozess starten möchtest, zum Beispiel das Anlegen einer Aufgabe, das Aktualisieren eines CRM-Eintrags, das Starten eines Reporting-Flows oder das Weiterleiten von Formulardaten in ein anderes System.

Beispiel: Newsartikel auf der Schulwebsite

Stell dir vor, die Schule hat einen n8n-Workflow erstellt, der einen Newsartikel auf der WordPress-Website der Schule veröffentlicht. In AI-School gibst du dann nur einen kurzen Textteil ein, zum Beispiel ein paar Sätze über eine Projektwoche, einen Sporttag oder einen Tag der offenen Tür. Mit diesem Text startest du den Workflow in n8n.

Der n8n-Workflow kann danach zum Beispiel:

1. Aus dem kurzen Text einen netten Konzepttext erstellen lassen mit einem LLM-Knoten und einer Prompt, die gut zum Ton der Schule passt.
2. Eine passende Illustration anfertigen lassen mit einem zweiten LLM-Knoten, zum Beispiel in den Farben der Schule 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-School und n8n zusammen: In AI-School wählt der Benutzer den Workflow und füllt die benötigten Informationen aus. n8n führt anschließend 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 Pflicht. 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 dem Knopf.
• Die eingegebenen Werte werden als JSON zusammen mit einem POST-Request an den n8n-Webhook gesendet.
• Ohne Rückmeldungen bestätigt AI-School lediglich, dass der Workflow gestartet wurde und in n8n weiterläuft. Das Fenster zeigt keinen Spinner und kann sofort geschlossen werden.
• Wenn dies bei der Registrierung aktiviert wurde, kann der Workflow Zwischenschritte oder das Ende an AI-School zurücksenden.
• Wenn die Freigabe bei der Registrierung aktiviert ist, kann der Benutzer eine Wahl direkt in AI-School treffen. n8n setzt danach ab dem wartenden Schritt fort.

n8n-Workflow in AI-School 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. Markiere unter Terugmeldungen uit n8n nur die Teile, die in diesem n8n-Workflow tatsächlich gebaut wurden: Fortschritt, Freigabe und/oder das Ende des Workflows.
7. Füge ggf. die Felder hinzu, die im POST-Request mitgeschickt werden sollen.
8. Speichere den Workflow.

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

Felder

• Felder sind optional.
• Jedes Feld hat einen Feldnamen und einen Typ.
• Unterstützte Feldtypen sind kurze Text, langer Text, Zahl, Ja/Nein, Datum, eine Auswahl und mehrere Auswahlen.
• Bei Eine Auswahl und Mehrere Auswahlen fügt man die verfügbaren Optionen hinzu. Eine Auswahl wird als kompakte Auswahlliste angezeigt; Mehrere Auswahlen zeigt Kontrollkästchen. Der ausgewählte Wert bzw. die Werte werden in der JSON-Body mitgesendet.
• Pflichtfelder müssen ausgefüllt werden, bevor der Workflow gestartet werden kann.
• Der Feldname wird zum Key in der 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 exakt den Namen Start workflow. Die weiter unten gezeigten Beispiele verwenden diesen Namen.
4. Setze HTTP Method auf POST.
5. Wähle bei Authentication Header Auth und wähle eine Header-Auth-Credential aus.
6. Trage in jener Credential denselben Header-Namen und denselben geheimen Wert ein wie beim Workflow in AI-School.
7. Setze Respond bzw. Response Mode auf Immediately. Die App erhält dann direkt eine erfolgreiche Startbestätigung, während n8n weiterarbeitet.
8. Kopiere die Production URL des Webhook-Knotens in das Feld n8n Produktion-url in AI-School. Verwende nicht die Test-URL mit /webhook-test/.
9. Aktiviere den Workflow in n8n.

Die Daten aus AI-School befinden sich in n8n unter body. Die Integrationsdaten befinden sich daher unter body.integration. Lösche diese Daten nicht in einem Edit Fields-, Set- oder Code-Knoten. Die untenstehenden Beispiele lesen sie immer direkt aus dem Knoten Start workflow.

Beispiel des JSON-Body

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

{
  "prompt": "Mach eine kurze Zusammenfassung des Antrags.",
  "kundename": "Beispielorganisation",
  "zielgruppen": ["Mitarbeiter", "Eltern"],
  "datum": "2026-09-22",
  "integration": {
    "runId": "chat-dokument-id",
    "tenant": "default",
    "callbackUrl": "https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowCallback",
    "callbackToken": "vorübergehendes-token-für-diesen-ausführung"
  }
}

Das Callback-Token gehört zu einer Ausführung. Speichere es nicht in Logs, in der festen Konfiguration oder in anderen Systemen.

Optional: Fortschritt und Abschluss zurückmelden

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

HTTP Request-Node einrichten

1. Füge eine HTTP Request-Node hinzu und nenne sie beispielsweise Fortschritt melden.

2. Setze Method auf POST.

3. Klicke bei URL auf Expression.

4. Füge exakt diese Expression ein:

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

5. Wähle bei Authentication None. Der temporäre Token wird in der nächsten Schritt als Header hinzugefügt.

6. Aktiviere Send Headers und füge diese zwei Headers hinzu:

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

7. Aktiviere Send Body.

8. Wähle Body Content Type: JSON und Specify Body: Using JSON.

9. Füge folgende JSON in das Feld JSON ein:

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

10. Wähle Execute step, während du den Workflow über die App testest. Der Knoten sollte Status 200 zurückerhalten.

Kopiere diesen HTTP Request-Node für jeden Status-Callback. Passe pro Kopie mindestens eventId, step.id, step.label und message an.

Letzten Callback einstellen

Wenn Das Ende des Workflows melden aktiviert ist, muss am Ende jeder möglichen Route ein letzter Callback stehen. Verwende type: "completed" bei Erfolg, type: "failed" bei einem Fehler, den du selbst behandelst, und type: "rejected" wenn der Benutzer den Workflow ablehnt.

Für eine erfolgreiche Ausführung kann der Body so aussehen:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "workflow-abgeschlossen",
  "type": "completed",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "abwicklung",
    "label": "Workflow abgeschlossen"
  },
  "message": "Der Workflow ist abgeschlossen.",
  "output": {
    "resultat": "Kurze Beschreibung oder Link zum Ergebnis"
  }
}

Verwende innerhalb einer Ausführung für jeden Callback eine andere eventId. Gib auch immer ein deutliches step.label an: Diese Textzeile sieht der Benutzer im Ausführungsfenster.

Optional: Freigabe in der App anfordern

Wait-Knoten einrichten

1. Füge an der Stelle, an der Freigabe benötigt wird, einen Wait-Knoten hinzu.
2. Wähle bei Resume On Webhook Call.
3. Setze HTTP Method auf POST.
4. Wähle bei Authentication Header Auth.
5. Wähle dieselbe Header-Auth-Credential wie beim Knoten Start workflow.
6. Platziere vor dem Wait-Knoten eine Kopie des zuvor eingerichteten HTTP Request-Knotens und benenne diese Freigabe anfordern.
7. Verwende in diesem Knoten dieselbe dynamische URL und dieselben Header. Ersetze nur den JSON-Body durch:

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

Verbinde Freigabe anfordern mit dem Wait-Knoten. Der Benutzer sieht danach die Buttons in AI-School. Die geheime Resume-URL wird dem Browser nicht gegeben; der Server sendet die Wahl sicher an den Wait-Knoten.

Wahl nach dem Wait-Knoten verarbeiten

1. Füge nach dem Wait-Knoten einen Switch-Knoten hinzu.

2. Verwende als zu prüfenden Wert:

   {{ $json.body.decision }}

3. Erstelle z. B. eine Route für approve und eine Route für reject.

4. Lasse jede Route mit einer passenden completed, rejected oder failed Callback enden.

Eine Auswahldaten darf nur Buchstaben, Zahlen, _ und - enthalten. Das Label darf verständliche Textzeichen enthalten.

Produktions-Callback-URL einstellen

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

https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowCallback

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

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

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

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

Unerwartete Fehler zurückmelden

Ein gewöhnlicher failed-Callback funktioniert nur, wenn der Workflow die betreffende HTTP Request-Node erreicht. Verwende zusätzlich einen zentralen n8n-Error-Workflow bei unerwarteten Fehlern der Nodes.

Zentralen Error-Workflow erstellen

1. Erstelle in n8n einen separaten Workflow mit dem Namen AI-School - Fehler zurückmelden.

2. Füge eine Error Trigger-Node hinzu.

3. Füge danach eine HTTP Request-Node hinzu.

4. Setze Method auf POST.

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

   https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowExecutionFailed

6. Wähle Authentication: None.

7. Aktiviere Send Headers und füge hinzu:

   Name	Value
   n8n-handihow-name	der geheime Standardwert, den du vom Plattform-Administrator erhältst
   Content-Type	application/json

8. Aktiviere Send Body, wähle JSON und füge folgenden Body ein:

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

9. Aktiviere die Error-Workflow.
10. Öffne die Einstellungen des normalen Workflows und wähle bei Error Workflow diesen neuen Error-Workflow aus.

Sende direkt nach dem Start workflow immer mindestens einen Fortschritts-Callback mit executionId: "{{ $execution.id }}". Dadurch weiß die App, zu welcher Ausführung ein unerwarteter n8n-Fehler gehört.

Wichtige Einschränkungen

• Nur Webhook-Trigger werden unterstützt.
• Nur Produktions-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-Token und Resume-URLs werden nur serverseitig verarbeitet und sind nicht direkt für Benutzer verfügbar.
• Die Tenant wird serverseitig aus dem eingeloggten Benutzer bestimmt, nicht aus einem Wert, den der Browser mitsendet.

Fehlerbehebung

• 404 oder Webhook nicht registriert: aktiviere den Workflow in n8n und verwende die Produktions-URL.
• Authentifizierungsfehler: prüfe, ob Header-Name und -Wert in beiden Systemen exakt übereinstimmen.
• Fehlende Daten: prüfe, ob die Feldnamen in der Anwendung mit den Keys übereinstimmen, die n8n erwartet.
• Kein Request in n8n: prüfe, ob der Workflow mit einem Webhook-Trigger beginnt und POST verwendet.
• Das Ausführungsfenster läuft weiter: Hast du Das Ende des Workflows melden aktiviert, prüfe, 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 Fortschritte sichtbar: überprü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-Buttons funktionieren nicht: prüfe den Wait-Knoten, resumeUrl, Header-Authentifizierung und zulässige Zeichen in choices[].value.