flussi n8n

AI-School può avviare flussi n8n tramite un webhook di produzione. Questo è utile quando vuoi avviare un processo automatizzato al di fuori di AI-School, ad esempio creare un task, aggiornare un record CRM, avviare un flusso di rapporti o inoltrare i dati di un modulo a un altro sistema.

Esempio: articolo di notizie sul sito della scuola

Supponiamo che la scuola abbia creato un flusso n8n che pubblica un articolo sul sito WordPress della scuola. In AI-School inserisci quindi solo un breve testo, ad esempio un paio di frasi su una settimana di progetti, giornata sportiva o giornata aperta. Con quel testo avvii il flusso in n8n.

Il flusso n8n può poi, ad esempio:

1. Prendere il testo breve e trasformarlo in una bozza accurata con una nodo LLM e un prompt adatto al tono della scuola.
2. Far creare un’illustrazione adatta con una seconda nodo LLM, ad esempio nei colori della scuola e in uno stile illustrativo riconoscibile.
3. Preparare o pubblicare il testo e l’immagine come post sul blog sul sito WordPress.

Così AI-School e n8n lavorano insieme: in AI-School l’utente sceglie il flusso e inserisce le informazioni necessarie. n8n esegue poi i passaggi automatizzati e garantisce che l’articolo sia correttamente sul sito.

Cosa fa questa integrazione?

Avvii un flusso n8n dall’overview del flusso. Sono obbligatori solo il webhook di produzione, POST e Header Auth. Campi e risposte da n8n sono opzionali e possono essere impostati indipendentemente l’uno dall’altro.

• Se il flusso non ha campi, il webhook viene invocato subito.
• Se il flusso ha campi, si apre prima un modulo. L’utente compila i campi e avvia quindi il flusso con il pulsante.
• I valori compilati vengono spediti come JSON in una richiesta POST al webhook n8n.
• Senza risposte, AI-School conferma solo che il flusso è stato avviato e continua su n8n. La finestra non mostra uno spinner e può essere chiusa subito.
• Se questo è abilitato durante la registrazione, il flusso può inviare indietro passi intermedi o la fine ad AI-School.
• Se l’approvazione è abilitata durante la registrazione, l’utente può fare una scelta direttamente in AI-School. n8n proseguirà da quel punto.

creazione del flusso n8n in AI-School

Un amministratore registra il flusso come segue:

1. Vai su Assistenten.
2. Apri Workflows.
3. Seleziona Nuovo flusso n8n.
4. Inserisci il nome del flusso e l’URL di produzione n8n.
5. Imposta Header authentication con un nome di header e un valore di header segreto.
6. Spunta sotto Terugmeldingen uit n8n solo gli elementi effettivamente costruiti in questo flusso n8n: avanzamento, approvazione e/o fine del flusso.
7. Aggiungi eventualmente i campi da inviare nel POST-request.
8. Salva il flusso.

Tutte e tre le opzioni di ritorno sono disabilitate di default. Se aggiungi in seguito callback o una fase di approvazione in n8n, aggiorna anche l’iscrizione in AI-School. La dialog è quindi in grado di mostrare solo una conferma di avvio o di attendere ulteriori segnali.

Campi

• I campi sono opzionali.
• Ogni campo ha un nome e un tipo.
• I tipi di campo supportati sono testo breve, testo lungo, numero, sì/no, data, una scelta e più scelte.
• Per Una scelta e Più scelte aggiungi le opzioni disponibili. Una Una scelta viene mostrata come menù a scelta compatto; Più scelte mostra caselle di controllo. Il valore selezionato o i valori vengono inviati nel corpo JSON.
• I campi obbligatori devono essere compilati prima che il flusso possa essere avviato.
• Il nome del campo diventa la chiave nel corpo JSON inviato a n8n.

Creazione di un flusso compatibile in n8n

1. Crea in n8n un nuovo flusso.
2. Aggiungi come prima node una Webhook.
3. Dai a questa node esattamente il nome Start workflow. Gli esempi qui sotto usano questo nome.
4. Imposta HTTP Method su POST.
5. Scegli Authentication su Header Auth e seleziona un credential di Header Auth.
6. Nella stessa credential inserisci lo stesso nome header e valore segreto come per il flusso in AI-School.
7. Imposta Respond o Response Mode su Immediately. L’app riceverà subito una conferma di avvio riuscita, mentre n8n continua a lavorare.
8. Copia la Production URL della Webhook-node nel campo n8n produzione-url in AI-School. Non usare l’URL di/test con /webhook-test/.
9. Attiva il flusso in n8n.

I dati da AI-School sono in n8n sotto body. I dati di integrazione sono quindi sotto body.integration. Non eliminare questi dati in un nodo Edit Fields-, Set- o Code. Gli esempi riportati di seguito li leggono sempre direttamente dalla nodo Start workflow.

Esempio del JSON body

Se definisci campi con nomi prompt, klantnaam, doelgroepen e datum, n8n riceverà ad esempio questo JSON body. AI-School aggiunge automaticamente l’oggetto integration.

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

Il token di callback è legato a una singola esecuzione. Non salvarlo nei log, in configurazioni fisse o in altri sistemi.

Opzionale: invio di avanzamento e completamento

AI-School può mostrare solo ciò che restituisce n8n. Usa queste callback solo se durante la registrazione hai abilitato Segnala avanzamento intermedio e/o Segnala fine del flusso.

Configurare nodo HTTP Request

1. Aggiungi un nodo HTTP Request e chiamalo ad esempio Segnala avanzamento.

2. Imposta Method su POST.

3. Clicca su URL su Expression.

4. Inserisci esattamente questa espressione:

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

5. Scegli Authentication su None. Il token temporaneo viene aggiunto come header al passo successivo.

6. Abilita Send Headers e aggiungi queste due intestazioni:

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

7. Abilita Send Body.

8. Imposta Body Content Type: JSON e Specify Body: Using JSON.

9. Incolla il JSON seguente nel campo 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. Imposta Execute step mentre testi il flusso tramite l’app. La node dovrebbe restituire stato 200.

Copia questa node di HTTP Request per ogni stato di segnalazione. Per ogni copia modifica almeno eventId, step.id, step.label e message.

Impostare l’ultima callback

Se è abilitato Segnala fine del flusso, a fine di ogni possibile percorso deve esserci una callback finale. Usa type: "completed" per successo, type: "failed" per un errore gestito, e type: "rejected" quando l’utente rifiuta il flusso.

Per un’esecuzione riuscita l’body può apparire così:

{
  "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": "Il flusso è stato completato.",
  "output": {
    "risultato": "Breve descrizione o link al risultato"
  }
}

Usa in una singola esecuzione per ogni callback un diverso eventId. Usa anche sempre un chiaro step.label: questo testo lo vede l’utente nella finestra di esecuzione.

Opzionale: richiedere approvazione nell’app

Impostare nodo Wait

1. Aggiungi un nodo Wait nel punto in cui è necessaria l’approvazione.
2. Scegli Resume su On Webhook Call.
3. Imposta HTTP Method su POST.
4. Scegli Authentication su Header Auth.
5. Seleziona la stessa credenziale Header Auth usata dal nodo Start workflow.
6. Inserisci prima del nodo Wait una copia dell’HTTP Request precedentemente impostato e chiamalo Richiedi approvazione.
7. Usa in questo nodo la stessa URL dinamica e headers. Sostituisci solo il corpo JSON con:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "controllo-document",
  "type": "approval_required",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "controle_document",
    "label": "Document controllare"
  },
  "approval": {
    "question": "La workflow può procedere?",
    "context": "Controlla prima il documento generato.",
    "resumeUrl": "{{ $execution.resumeUrl }}",
    "choices": [
      { "value": "approve", "label": "Approva" },
      { "value": "reject", "label": "Rifiuta" }
    ]
  }
}

Collega Richiedi approvazione al nodo Wait. L’utente vedrà quindi i pulsanti in AI-School. La resume-url segreta non viene mostrata al browser; il server invia in modo sicuro la scelta al nodo Wait.

Elaborare la scelta dopo Wait

1. Aggiungi dopo il nodo Wait un nodo Switch.

2. Usa come valore da controllare:

   {{ $json.body.decision }}

3. Ad esempio crea una route per approve e una route per reject.

4. Fai terminare ogni route con una callback adeguata completed, rejected o failed.

Un valore di scelta può contenere solo lettere, numeri, _ e -. L’etichetta può contenere testo leggibile.

Impostare l’URL di callback di produzione

L’URL di callback di produzione per AI-School è:

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

Non incollare questo URL come testo fisso in ogni nodo callback. Seleziona nel campo URL del nodo HTTP Request l’opzione Expression e usa:

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

AI-School fornisce quindi automaticamente l’URL di produzione corretto ad ogni avvio. L’URL fisso sopra viene usato solo per controllare durante i test che l’espressione punti ad AI-School.

Le callable triggerCustomN8nWorkflow, triggerN8nWorkflow e resumeN8nWorkflow vengono richiamate direttamente dall’app. Non è necessario impostarle in n8n.

Inviare errori inaspettati

Una callback standard failed funziona solo se la node HTTP Request raggiunge la rispettiva nodo. Per errori inattesi nelle node, usa anche un flusso di errore n8n centrale.

Creare un flusso di errore centrale

1. Crea in n8n un flusso separato chiamato AI-School - errori da inviare.

2. Aggiungi una node Error Trigger.

3. Aggiungi poi una node HTTP Request.

4. Imposta Method su POST.

5. Inserisci in URL questa production URL fissa:

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

6. Scegli Authentication: None.

7. Abilita Send Headers e aggiungi:

   Name	Value
   n8n-handihow-name	la valore segreto standard fornito dall’amministratore della piattaforma
   Content-Type	application/json

8. Abilita Send Body, scegli JSON e incolla questo body:

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

9. Attiva il Flusso di Errore.
10. Apri le impostazioni del flusso normale e seleziona come Error Workflow questo nuovo Flusso di Errore.

Invia immediatamente dopo Start workflow almeno una callback di avanzamento con executionId: "{{ $execution.id }}". In questo modo l’app saprà a quale esecuzione appartiene un errore n8n inaspettato.

Vincoli importanti

• Sono supportati solo trigger webhook.
• Sono supportati solo URL di webhook di produzione.
• I webhook di test con /webhook-test/ sono rifiutati.
• Sono supportati solo POST.
• È supportata solo Generic header authentication.
• Il valore dell’header è trattato come secret dall’applicazione.
• I token di callback e gli URL di resume sono elaborati solo lato server e non sono disponibili direttamente per gli utenti.
• Il tenant è determinato lato server dall’utente loggato, non da un valore inviato dal browser.

Risoluzione dei problemi

• 404 o webhook non registrato: attiva il flusso in n8n e usa l’URL di produzione.
• Errore di autenticazione: verifica che il nome e il valore dell’header siano esatti in entrambi i sistemi.
• Dati mancanti: controlla che i nomi dei campi nell’app corrispondano alle chiavi attese da n8n.
• Nessuna richiesta in n8n: controlla che il flusso inizi con un trigger webhook e usi POST.
• La finestra di esecuzione resta aperta: se hai abilitato Segnala fine del flusso, verifica che n8n invii una callback finale completed, failed o rejected. Se non prevedi risposte, disattiva tutte e tre le opzioni nella registrazione.
• Nessuna visibilità di avanzamento: controlla che in registrazione sia abilitato Segnala avanzamento intermedio, oppure che l’oggetto integration sia mantenuto e che ogni callback abbia un unico eventId.
• Pulsanti di approvazione non funzionano: controlla la Wait node, resumeUrl, l’autenticazione header e i caratteri consentiti in choices[].value.