n8n workflows

AI-School kan n8n workflows starten via een productie-webhook. Dit is handig wanneer je buiten AI-School een geautomatiseerd proces wilt starten, bijvoorbeeld het aanmaken van een taak, bijwerken van een CRM-record, starten van een rapportageflow of doorzetten van formuliergegevens naar een ander systeem.

Voorbeeld: nieuwsartikel op de schoolwebsite

Stel dat de school een n8n workflow heeft gemaakt die een nieuwsartikel publiceert op de WordPress website van de school. In AI-School vul je dan alleen een kort stukje tekst in, bijvoorbeeld een paar zinnen over een projectweek, sportdag of open dag. Met die tekst start je de workflow in n8n.

De n8n workflow kan daarna bijvoorbeeld:

1. Van de korte tekst een nette concepttekst maken met een LLM node en een prompt die goed past bij de toon van de school.
2. Een passende illustratie laten maken met een tweede LLM node, bijvoorbeeld in de kleuren van de school en in een herkenbare illustratieve stijl.
3. De tekst en afbeelding als blogbericht klaarzetten of publiceren op de WordPress website.

Zo werken AI-School en n8n samen: in AI-School kiest de gebruiker de workflow en vult de benodigde informatie in. n8n voert daarna de geautomatiseerde stappen uit en zorgt dat het nieuwsartikel netjes op de website terechtkomt.

Wat doet deze integratie?

Je start een n8n workflow vanuit het workflow-overzicht. Alleen de productie-webhook, POST en Header Auth zijn verplicht. Velden en terugmeldingen vanuit n8n zijn optioneel en kunnen onafhankelijk van elkaar worden ingesteld.

• Heeft de workflow geen velden, dan wordt de webhook meteen aangeroepen.
• Heeft de workflow wel velden, dan opent eerst een formulier. De gebruiker vult de velden in en start daarna de workflow met de knop.
• De ingevulde waarden worden als JSON meegestuurd in een POST-request naar de n8n webhook.
• Zonder terugmeldingen bevestigt AI-School alleen dat de workflow is gestart en verder loopt in n8n. Het venster toont geen spinner en kan direct worden gesloten.
• Als dit bij de registratie is aangezet, kan de workflow tussentijdse stappen of het einde terugsturen naar AI-School.
• Als goedkeuring bij de registratie is aangezet, kan de gebruiker een keuze rechtstreeks in AI-School maken. n8n gaat daarna verder vanaf de wachtende stap.

n8n workflow aanmaken in AI-School

Een beheerder registreert de workflow als volgt:

1. Ga naar Assistenten.
2. Open Workflows.
3. Kies Nieuwe n8n workflow.
4. Vul de naam van de workflow en de n8n productie-url in.
5. Stel Header authentication in met een header name en geheime header value.
6. Vink onder Terugmeldingen uit n8n alleen de onderdelen aan die werkelijk in deze n8n-workflow zijn gebouwd: voortgang, goedkeuring en/of het einde van de workflow.
7. Voeg eventueel de velden toe die moeten worden meegestuurd in het POST-request.
8. Sla de workflow op.

Alle drie de terugmeldingsopties staan standaard uit. Zet je later callbacks of een goedkeuringsstap in n8n, werk dan ook de registratie in AI-School bij. De dialog weet daardoor of hij alleen een startbevestiging moet tonen of op verdere signalen moet blijven wachten.

Velden

• Velden zijn optioneel.
• Elk veld heeft één veldnaam en een type.
• Ondersteunde veldtypes zijn korte tekst, lange tekst, getal, ja/nee, datum, één keuze en meerdere keuzes.
• Bij Eén keuze en Meerdere keuzes voeg je de beschikbare opties toe. Eén keuze wordt als compacte keuzelijst getoond; Meerdere keuzes toont selectievakjes. De gekozen waarde of waarden worden in de JSON body meegestuurd.
• Verplichte velden moeten zijn ingevuld voordat de workflow kan worden gestart.
• De veldnaam wordt de key in de JSON body die naar n8n wordt gestuurd.

Compatibele workflow maken in n8n

1. Maak in n8n een nieuwe workflow.
2. Voeg als eerste node een Webhook toe.
3. Geef deze node exact de naam Start workflow. De voorbeelden verderop gebruiken deze naam.
4. Zet HTTP Method op POST.
5. Kies bij Authentication voor Header Auth en selecteer een Header Auth credential.
6. Vul in die credential dezelfde headernaam en geheime waarde in als bij de workflow in AI-School.
7. Zet Respond of Response Mode op Immediately. De app krijgt dan direct een succesvolle startbevestiging, terwijl n8n verder werkt.
8. Kopieer de Production URL van de Webhook-node naar het veld n8n productie-url in AI-School. Gebruik niet de test-url met /webhook-test/.
9. Activeer de workflow in n8n.

De gegevens uit AI-School staan in n8n onder body. De integratiegegevens staan daardoor onder body.integration. Verwijder deze gegevens niet in een Edit Fields-, Set- of Code-node. De voorbeelden hieronder lezen ze steeds rechtstreeks terug uit de node Start workflow.

Voorbeeld van de JSON body

Als je velden definieert met de namen prompt, klantnaam, doelgroepen en datum, ontvangt n8n bijvoorbeeld deze JSON body. AI-School voegt het integration-object automatisch toe.

{
  "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"
  }
}

Het callbacktoken hoort bij één uitvoering. Sla het niet op in logs, vaste configuratie of andere systemen.

Optioneel: voortgang en afronding terugsturen

AI-School kan alleen tonen wat n8n terugmeldt. Gebruik deze callbacks alleen als je bij de registratie Tussentijdse voortgang melden en/of Het einde van de workflow melden hebt aangezet.

HTTP Request node instellen

1. Voeg een HTTP Request node toe en noem deze bijvoorbeeld Meld voortgang.

2. Zet Method op POST.

3. Klik bij URL op Expression.

4. Plak exact deze expressie:

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

5. Kies bij Authentication voor None. Het tijdelijke token wordt in de volgende stap als header toegevoegd.

6. Zet Send Headers aan en voeg deze twee headers toe:

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

7. Zet Send Body aan.

8. Kies Body Content Type: JSON en Specify Body: Using JSON.

9. Plak onderstaande JSON in het veld JSON:

{
  "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. Kies Execute step terwijl je de workflow via de app test. De node hoort status 200 terug te krijgen.

Kopieer deze HTTP Request node voor iedere statusmelding. Pas per kopie minimaal eventId, step.id, step.label en message aan.

Laatste callback instellen

Als Het einde van de workflow melden is aangezet, moet aan het einde van iedere mogelijke route een laatste callback staan. Gebruik type: "completed" bij succes, type: "failed" bij een fout die je zelf afhandelt en type: "rejected" wanneer de gebruiker de workflow afwijst.

Voor een geslaagde uitvoering kan de body er zo uitzien:

{
  "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"
  }
}

Gebruik binnen één uitvoering voor iedere callback een andere eventId. Gebruik ook altijd een duidelijke step.label: deze tekst ziet de gebruiker in het uitvoeringsvenster.

Optioneel: goedkeuring vragen in de app

Wait node instellen

1. Voeg op de plaats waar goedkeuring nodig is een Wait node toe.
2. Kies bij Resume voor On Webhook Call.
3. Zet HTTP Method op POST.
4. Kies bij Authentication voor Header Auth.
5. Selecteer dezelfde Header Auth credential als bij de node Start workflow.
6. Plaats vóór de Wait node een kopie van de eerder ingestelde HTTP Request node en noem deze Vraag goedkeuring.
7. Gebruik in deze node dezelfde dynamische URL en headers. Vervang alleen de JSON body door:

{
  "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" }
    ]
  }
}

Verbind Vraag goedkeuring met de Wait node. De gebruiker ziet daarna de knoppen in AI-School. De geheime resume-url wordt niet aan de browser gegeven; de server stuurt de keuze veilig naar de Wait node.

Keuze na de Wait node verwerken

1. Voeg na de Wait node een Switch node toe.

2. Gebruik als te controleren waarde:

   {{ $json.body.decision }}

3. Maak bijvoorbeeld een route voor approve en een route voor reject.

4. Laat iedere route eindigen met een passende completed, rejected of failed callback.

Een keuzewaarde mag alleen letters, cijfers, _ en - bevatten. Het label mag wel gewone leesbare tekst bevatten.

Productie callback-url instellen

De productie callback-url voor AI-School is:

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

Plak deze URL niet als vaste tekst in iedere callbacknode. Kies in het URL-veld van de HTTP Request node Expression en gebruik:

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

AI-School levert daarmee bij iedere start automatisch de juiste productie-url aan. De vaste URL hierboven gebruik je alleen om tijdens het testen te controleren of de expressie naar AI-School verwijst.

De callables triggerCustomN8nWorkflow, triggerN8nWorkflow en resumeN8nWorkflow worden door de app zelf aangeroepen. Deze URL's hoef je niet in n8n in te stellen.

Onverwachte fouten terugsturen

Een gewone failed callback werkt alleen wanneer de workflow de betreffende HTTP Request node bereikt. Gebruik voor onverwachte nodefouten daarnaast een centrale n8n Error Workflow.

Centrale Error Workflow maken

1. Maak in n8n een aparte workflow met de naam AI-School - fouten terugsturen.

2. Voeg een Error Trigger node toe.

3. Voeg daarna een HTTP Request node toe.

4. Zet Method op POST.

5. Vul bij URL deze vaste productie-URL in:

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

6. Kies Authentication: None.

7. Zet Send Headers aan en voeg toe:

   Name	Value
   n8n-handihow-name	de geheime standaardwaarde die je van de platformbeheerder ontvangt
   Content-Type	application/json

8. Zet Send Body aan, kies JSON en plak deze body:

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

9. Activeer de Error Workflow.
10. Open de instellingen van de gewone workflow en selecteer bij Error Workflow deze nieuwe Error Workflow.

Stuur direct na Start workflow altijd minimaal één voortgangscallback met executionId: "{{ $execution.id }}". Daardoor weet de app bij welke uitvoering een onverwachte n8n-fout hoort.

Belangrijke beperkingen

• Alleen webhook triggers worden ondersteund.
• Alleen productie-webhook-urls worden ondersteund.
• Test-webhook-urls met /webhook-test/ worden geweigerd.
• Alleen POST wordt ondersteund.
• Alleen generic header authentication wordt ondersteund.
• De header value wordt in de applicatie als geheim behandeld.
• Callbacktokens en resume-url's worden alleen server-side verwerkt en zijn niet rechtstreeks beschikbaar voor gebruikers.
• De tenant wordt server-side bepaald vanuit de ingelogde gebruiker, niet vanuit een waarde die de browser meestuurt.

Problemen oplossen

• 404 of webhook niet geregistreerd: activeer de workflow in n8n en gebruik de productie-url.
• Authenticatiefout: controleer of header name en value in beide systemen exact gelijk zijn.
• Ontbrekende data: controleer of de veldnamen in de applicatie overeenkomen met de keys die n8n verwacht.
• Geen request in n8n: controleer of de workflow begint met een webhook trigger en POST gebruikt.
• Het uitvoeringsvenster blijft draaien: heb je Het einde van de workflow melden aangezet, controleer dan of n8n een laatste completed, failed of rejected callback verstuurt. Verwacht je geen terugmeldingen, zet dan alle drie de opties bij de registratie uit.
• Geen voortgang zichtbaar: controleer of Tussentijdse voortgang melden bij de registratie aanstaat, of het integration-object behouden blijft en of iedere callback een unieke eventId heeft.
• Goedkeuringsknoppen werken niet: controleer de Wait node, resumeUrl, header authentication en de toegestane tekens in choices[].value.