workflow n8n

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

Esempio: articolo di notizie sul sito della scuola

Supponiamo che la scuola abbia creato un workflow n8n che pubblica un articolo di notizie sul sito WordPress della scuola. In AI-School compili solo un breve testo, ad esempio alcune frasi su una settimana progetto, una giornata sportiva o un open day. Con quel testo avvii il workflow in n8n.

Il workflow n8n può poi, ad esempio:

1. Trasformare il breve testo in una bozza ordinata con un nodo LLM e un prompt adatto al tono della scuola.
2. Generare un’illustrazione adatta con un secondo nodo LLM, ad esempio nei colori della scuola e in uno stile illustrativo riconoscibile.
3. Preparare o pubblicare il testo e l’immagine come articolo del blog sul sito WordPress.

In questo modo AI-School e n8n lavorano insieme: in AI-School l’utente sceglie il workflow e inserisce le informazioni necessarie. n8n esegue poi i passaggi automatizzati e fa sì che l’articolo di notizie finisca correttamente sul sito.

Cosa fa questa integrazione?

Avvii un workflow n8n dalla panoramica dei workflow. Sono obbligatori solo il webhook di produzione, POST e Header Auth. I campi e i callback da n8n sono facoltativi e possono essere configurati indipendentemente l’uno dall’altro.

• Se il workflow non ha campi, il webhook viene richiamato immediatamente.
• Se il workflow ha dei campi, si apre prima un modulo. L’utente compila i campi e poi avvia il workflow con il pulsante.
• I valori inseriti vengono inviati come JSON in una richiesta POST al webhook n8n.
• Senza callback, AI-School conferma solo che il workflow è stato avviato e continua in n8n. La finestra non mostra uno spinner e può essere chiusa subito.
• Se attivato durante la registrazione, il workflow può inviare ad AI-School i passaggi intermedi o la fine.
• Se l’approvazione è stata attivata durante la registrazione, l’utente può fare una scelta direttamente in AI-School. n8n prosegue poi dalla fase di attesa.

Creare un workflow n8n in AI-School

Un amministratore registra il workflow nel modo seguente:

1. Vai su Assistenti.
2. Apri la scheda Assistenti workflow.
3. Nella scheda in alto fai clic su Nuovo workflow e scegli workflow n8n.
4. Inserisci il nome del workflow e l’URL di produzione n8n.
5. Configura Header authentication con un nome header e un valore header segreto.
6. In Callback da n8n seleziona solo le parti effettivamente implementate in questo workflow n8n: avanzamento, approvazione e/o fine del workflow.
7. Aggiungi eventualmente i campi che devono essere inviati nella richiesta POST.
8. Salva il workflow.

Tutte e tre le opzioni di callback sono disattivate per impostazione predefinita. Se in seguito aggiungi callback o una fase di approvazione in n8n, aggiorna anche la registrazione in AI-School. Il dialog sa così se deve mostrare solo una conferma di avvio oppure attendere altri segnali.

Campi

• I campi sono opzionali.
• Ogni campo ha un nome campo e un tipo.
• I tipi 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 scelta viene mostrata come elenco compatto; Più scelte mostra caselle di selezione. Il valore o i valori scelti vengono inviati nel body JSON.
• I campi obbligatori devono essere compilati prima che il workflow possa essere avviato.
• Il nome del campo diventa la key nel body JSON inviato a n8n.

Creare un workflow compatibile in n8n

1. Crea un nuovo workflow in n8n.
2. Aggiungi come primo nodo un Webhook.
3. Dai a questo nodo esattamente il nome Start workflow. Gli esempi più avanti usano questo nome.
4. Imposta HTTP Method su POST.
5. In Authentication scegli Header Auth e seleziona una credenziale Header Auth.
6. Inserisci in quella credenziale lo stesso nome header e lo stesso valore segreto usati nel workflow in AI-School.
7. Imposta Respond o Response Mode su Immediately. L’app riceve così subito una conferma di avvio riuscito, mentre n8n continua a lavorare.
8. Copia la Production URL del nodo Webhook nel campo n8n productie-url in AI-School. Non usare l’URL di test con /webhook-test/.
9. Attiva il workflow in n8n.

I dati di AI-School in n8n si trovano sotto body. I dati di integrazione si trovano quindi sotto body.integration. Non rimuovere questi dati in un nodo Edit Fields, Set o Code. Gli esempi qui sotto li leggono sempre direttamente dal nodo Start workflow.

Esempio del body JSON

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

{
  "prompt": "Crea un breve riepilogo della richiesta.",
  "klantnaam": "Organizzazione di esempio",
  "doelgroepen": ["dipendenti", "genitori"],
  "datum": "2026-09-22",
  "integration": {
    "runId": "chat-document-id",
    "tenant": "default",
    "callbackUrl": "https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowCallback",
    "callbackToken": "token-temporaneo-per-questa-esecuzione"
  }
}

Il callback token appartiene a una sola esecuzione. Non salvarlo in log, configurazioni fisse o altri sistemi.

Opzionale: inviare avanzamento e completamento

AI-School può mostrare solo ciò che n8n segnala. Usa questi callback solo se in registrazione hai attivato Segnalare avanzamento intermedio e/o Segnalare la fine del workflow.

Configurare il nodo HTTP Request

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

2. Imposta Method su POST.

3. In URL fai clic su Expression.

4. Incolla esattamente questa espressione:

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

5. In Authentication scegli None. Il token temporaneo viene aggiunto come header nel passaggio successivo.

6. Attiva Send Headers e aggiungi questi due header:

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

7. Attiva Send Body.

8. Scegli 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": "Creazione documento"
  },
  "message": "Il documento viene creato."
}

10. Scegli Execute step mentre testi il workflow tramite l’app. Il nodo dovrebbe restituire status 200.

Copia questo nodo HTTP Request per ogni messaggio di stato. Modifica per ogni copia almeno eventId, step.id, step.label e message.

Configurare il callback finale

Se Segnalare la fine del workflow è attivo, alla fine di ogni possibile percorso deve esserci un callback finale. Usa type: "completed" in caso di successo, type: "failed" per un errore gestito manualmente e type: "rejected" quando l’utente rifiuta il workflow.

Per un’esecuzione riuscita il body può essere 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 completato"
  },
  "message": "Il workflow è stato completato.",
  "output": {
    "resultaat": "Breve descrizione o link al risultato"
  }
}

All’interno di una singola esecuzione usa un eventId diverso per ogni callback. Usa sempre anche un step.label chiaro: questo testo viene mostrato all’utente nella finestra di esecuzione.

Opzionale: chiedere approvazione nell’app

Configurare il nodo Wait

1. Nel punto in cui serve l’approvazione aggiungi un nodo Wait.
2. In Resume scegli On Webhook Call.
3. Imposta HTTP Method su POST.
4. In Authentication scegli Header Auth.
5. Seleziona la stessa credenziale Header Auth del nodo Start workflow.
6. Prima del nodo Wait inserisci una copia del nodo HTTP Request configurato in precedenza e chiamala Richiedi approvazione.
7. Usa in questo nodo lo stesso URL dinamico e gli stessi header. Sostituisci solo il body JSON con:

{
  "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": "Controllare il documento"
  },
  "approval": {
    "question": "Il workflow può proseguire?",
    "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à poi i pulsanti in AI-School. L’URL segreto di ripresa non viene fornito al browser; il server invia la scelta in modo sicuro al nodo Wait.

Elaborare la scelta dopo il nodo Wait

1. Dopo il nodo Wait aggiungi un nodo Switch.

2. Usa come valore da controllare:

   {{ $json.body.decision }}

3. Crea ad esempio un percorso per approve e uno per reject.

4. Fai terminare ogni percorso con un callback appropriato completed, rejected o failed.

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

Configurare 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 di callback. Nel campo URL del nodo HTTP Request scegli Expression e usa:

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

AI-School fornisce così automaticamente a ogni avvio l’URL di produzione corretto. L’URL fisso sopra serve solo per verificare durante i test che l’espressione punti ad AI-School.

Le callable triggerCustomN8nWorkflow, triggerN8nWorkflow e resumeN8nWorkflow vengono richiamate direttamente dall’app. Non devi impostare questi URL in n8n.

Inviare errori imprevisti

Un normale callback failed funziona solo quando il workflow raggiunge il relativo nodo HTTP Request. Per errori imprevisti dei nodi usa anche un n8n Error Workflow centrale.

Creare un Error Workflow centrale

1. Crea in n8n un workflow separato con il nome AI-School - fouten terugsturen.

2. Aggiungi un nodo Error Trigger.

3. Aggiungi poi un nodo HTTP Request.

4. Imposta Method su POST.

5. Inserisci in URL questo URL di produzione fisso:

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

6. Scegli Authentication: None.

7. Attiva Send Headers e aggiungi:

   Name	Value
   n8n-handihow-name	il valore standard segreto che ricevi dall’amministratore della piattaforma
   Content-Type	application/json

8. Attiva 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 l’Error Workflow.
10. Apri le impostazioni del workflow normale e seleziona questo nuovo Error Workflow in Error Workflow.

Subito dopo Start workflow invia sempre almeno un callback di avanzamento con executionId: "{{ $execution.id }}". In questo modo l’app sa a quale esecuzione appartiene un errore n8n imprevisto.

Limitazioni importanti

• Sono supportati solo i trigger webhook.
• Sono supportati solo gli URL webhook di produzione.
• Gli URL di test con /webhook-test/ vengono rifiutati.
• È supportato solo POST.
• È supportata solo l’autenticazione generic header.
• Il valore dell’header viene trattato come segreto nell’applicazione.
• I callback token e gli URL di ripresa vengono elaborati solo lato server e non sono direttamente disponibili per gli utenti.
• Il tenant viene determinato lato server a partire dall’utente autenticato, non da un valore inviato dal browser.

Risoluzione dei problemi

• 404 o webhook non registrato: attiva il workflow in n8n e usa l’URL di produzione.
• Errore di autenticazione: controlla che nome header e valore siano esattamente uguali in entrambi i sistemi.
• Dati mancanti: controlla che i nomi dei campi nell’applicazione corrispondano alle key attese da n8n.
• Nessuna richiesta in n8n: controlla che il workflow inizi con un trigger webhook e usi POST.
• La finestra di esecuzione continua a girare: se hai attivato Segnalare la fine del workflow, controlla che n8n invii un ultimo callback completed, failed o rejected. Se non ti aspetti callback, disattiva tutte e tre le opzioni nella registrazione.
• Nessun avanzamento visibile: controlla che Segnalare avanzamento intermedio sia attivo nella registrazione, che l’oggetto integration venga mantenuto e che ogni callback abbia un eventId univoco.
• I pulsanti di approvazione non funzionano: controlla il nodo Wait, resumeUrl, l’autenticazione header e i caratteri consentiti in choices[].value.