n8n-Workflows

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

Beispiel: Nachrichtenartikel auf der Schulwebsite

Angenommen, die Schule hat einen n8n-Workflow erstellt, der einen Nachrichtenartikel auf der WordPress-Website der Schule veröffentlicht. In AI-School füllst du dann nur einen kurzen Text 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 mit einem LLM-Node und einem Prompt, der gut zum Ton der Schule passt, einen sauberen Entwurfstext machen.
2. Mit einem zweiten LLM-Node eine passende Illustration erstellen lassen, zum Beispiel in den Farben der Schule und in einem wiedererkennbaren illustrativen Stil.
3. Den Text und das Bild als Blogbeitrag auf der WordPress-Website vorbereiten oder veröffentlichen.

So arbeiten AI-School und n8n zusammen: In AI-School 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 Nachrichtenartikel ordentlich auf der Website landet.

Was macht diese Integration?

Du startest einen n8n-Workflow über die Workflow-Übersicht. Nur der Produktions-Webhook, POST und Header Auth sind verpflichtend. Felder und Rückmeldungen aus n8n sind optional und können unabhängig voneinander konfiguriert 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 eingegebenen Werte werden als JSON in einem POST-Request an den n8n-Webhook gesendet.
• Ohne Rückmeldungen bestätigt AI-School nur, 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 Zwischenstände oder das Ende an AI-School zurücksenden.
• Wenn bei der Registrierung eine Freigabe aktiviert wurde, kann der Benutzer eine Auswahl direkt in AI-School treffen. n8n fährt danach ab dem wartenden Schritt fort.

n8n-Workflow in AI-School anlegen

Ein Administrator registriert den Workflow wie folgt:

1. Gehe zu Assistenten.
2. Öffne den Tab Workflow-Assistenten.
3. Klicke in der Karte oben auf Neuer Workflow und wähle n8n-Workflow.
4. Gib den Namen des Workflows und die n8n-Produktions-URL ein.
5. Richte Header authentication mit einem Header-Namen und einem geheimen Header-Wert ein.
6. Aktiviere unter Rückmeldungen aus n8n nur die Teile, die tatsächlich in diesem n8n-Workflow gebaut sind: Fortschritt, Freigabe und/oder das Ende des Workflows.
7. Füge optional die Felder hinzu, die im POST-Request mitgesendet werden sollen.
8. Speichere den Workflow.

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

Felder

• Felder sind optional.
• Jedes Feld hat genau einen Feldnamen und einen Typ.
• Unterstützte Feldtypen sind Kurztext, Langtext, Zahl, Ja/Nein, Datum, eine Auswahl und mehrere Auswahlen.
• Bei Eine Auswahl und Mehrere Auswahlen fügst du die verfügbaren Optionen hinzu. Eine Auswahl wird als kompaktes Auswahlfeld angezeigt; Mehrere Auswahlen zeigt Kontrollkästchen. Der gewählte Wert bzw. die gewählten Werte werden im JSON-Body mitgesendet.
• Pflichtfelder müssen ausgefüllt sein, bevor der Workflow gestartet werden kann.
• Der Feldname wird zum Key im JSON-Body, der an n8n gesendet wird.

Kompatiblen Workflow in n8n erstellen

1. Erstelle in n8n einen neuen Workflow.
2. Füge als ersten Node einen Webhook hinzu.
3. Gib diesem Node genau den Namen Start workflow. Die Beispiele weiter unten 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 diese Credential denselben Headernamen und denselben geheimen Wert ein wie beim Workflow in AI-School.
7. Setze Respond oder 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-Nodes in das Feld n8n productie-url in AI-School. Verwende nicht die Test-URL mit /webhook-test/.
9. Aktiviere den Workflow in n8n.

Die Daten aus AI-School stehen in n8n unter body. Die Integrationsdaten stehen deshalb unter body.integration. Entferne diese Daten nicht in einem Edit Fields-, Set- oder Code-Node. Die Beispiele unten lesen sie immer direkt aus dem Node Start workflow aus.

Beispiel des JSON-Bodys

Wenn du Felder mit den Namen prompt, klantnaam, doelgroepen und datum definierst, empfängt n8n zum Beispiel diesen JSON-Body. AI-School fügt das integration-Objekt automatisch hinzu.

{
  "prompt": "Maak een korte samenvatting van de aanvraag.",
  "klantnaam": "Voorbeeldorganisatie",
  "doelgroepen": ["medewerkers", "ouders"],
  "datum": "2026-09-22",
  "integration": {
    "runId": "chat-document-id",
    "tenant": "default",
    "callbackUrl": "https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowCallback",
    "callbackToken": "tijdelijk-token-voor-deze-uitvoering"
  }
}

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

Optional: Fortschritt und Abschluss zurücksenden

AI-School kann nur anzeigen, was n8n zurückmeldet. Verwende diese Callbacks nur, wenn du bei der Registrierung Zwischenzeitlichen Fortschritt melden und/oder Das Ende des Workflows melden aktiviert hast.

HTTP-Request-Node einrichten

1. Füge einen HTTP Request-Node hinzu und nenne ihn zum Beispiel Meld voortgang.

2. Setze Method auf POST.

3. Klicke bei URL auf Expression.

4. Füge genau diesen Ausdruck ein:

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

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

6. Aktiviere Send Headers und füge diese beiden Header 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 das 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-gestart",
  "type": "progress",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "document_maken",
    "label": "Document maken"
  },
  "message": "Het document wordt gemaakt."
}

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

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

Letzten Callback einrichten

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-afgerond",
  "type": "completed",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "afronding",
    "label": "Workflow afgerond"
  },
  "message": "De workflow is afgerond.",
  "output": {
    "resultaat": "Korte omschrijving of link naar het resultaat"
  }
}

Verwende innerhalb einer Ausführung für jeden Callback eine andere eventId. Verwende außerdem immer eine klare step.label: Dieser Text wird dem Benutzer im Ausführungsfenster angezeigt.

Optional: Freigabe in der App anfordern

Wait-Node einrichten

1. Füge an der Stelle, an der eine Freigabe nötig ist, einen Wait-Node 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 Node Start workflow aus.
6. Platziere vor dem Wait-Node eine Kopie des zuvor eingerichteten HTTP-Request-Nodes und nenne ihn Vraag goedkeuring.
7. Verwende in diesem Node 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": "Document controleren"
  },
  "approval": {
    "question": "Mag de workflow doorgaan?",
    "context": "Controleer eerst het gegenereerde document.",
    "resumeUrl": "{{ $execution.resumeUrl }}",
    "choices": [
      { "value": "approve", "label": "Goedkeuren" },
      { "value": "reject", "label": "Afwijzen" }
    ]
  }
}

Verbinde Vraag goedkeuring mit dem Wait-Node. Der Benutzer sieht danach die Schaltflächen in AI-School. Die geheime Resume-URL wird nicht an den Browser weitergegeben; der Server sendet die Auswahl sicher an den Wait-Node.

Auswahl nach dem Wait-Node verarbeiten

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

2. Verwende als zu prüfenden Wert:

   {{ $json.body.decision }}

3. Erstelle zum Beispiel einen Pfad für approve und einen Pfad für reject.

4. Lasse jeden Pfad mit einem passenden completed, rejected oder failed Callback enden.

Ein Auswahlwert darf nur Buchstaben, Zahlen, _ und - enthalten. Das Label darf jedoch normalen lesbaren Text enthalten.

Produktions-Callback-URL einrichten

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

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

Füge diese URL nicht als festen Text in jeden Callback-Node ein. Wähle im URL-Feld des HTTP-Request-Nodes Expression und verwende:

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

AI-School liefert damit bei jedem Start automatisch die richtige Produktions-URL mit. Die feste URL oben verwendest du nur, um beim Testen zu prüfen, ob der Ausdruck auf AI-School verweist.

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

Unerwartete Fehler zurücksenden

Ein gewöhnlicher failed-Callback funktioniert nur, wenn der Workflow den betreffenden HTTP-Request-Node erreicht. Verwende für unerwartete Node-Fehler zusätzlich einen zentralen n8n-Error-Workflow.

Zentralen Error-Workflow erstellen

1. Erstelle in n8n einen separaten Workflow mit dem Namen AI-School - fouten terugsturen.

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

3. Füge danach einen 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	de geheime Standardwert, den du vom Plattformadministrator erhältst
   Content-Type	application/json

8. Aktiviere Send Body, wähle JSON und füge diesen 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 den Error-Workflow.
10. Öffne die Einstellungen des normalen Workflows und wähle bei Error Workflow diesen neuen Error-Workflow aus.

Sende direkt nach 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

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

Probleme lösen

• 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 gleich sind.
• 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 bleibt aktiv: Hast du Das Ende des Workflows melden aktiviert, prüfe dann, ob n8n einen letzten completed, failed oder rejected-Callback sendet. Erwartest du keine Rückmeldungen, deaktiviere bei der Registrierung alle drei Optionen.
• Kein Fortschritt sichtbar: Prüfe, ob Zwischenzeitlichen Fortschritt melden bei der Registrierung aktiviert ist, ob das integration-Objekt erhalten bleibt und ob jeder Callback eine eindeutige eventId hat.
• Freigabeschaltflächen funktionieren nicht: Prüfe den Wait-Node, resumeUrl, Header-Authentifizierung und die erlaubten Zeichen in choices[].value.