flussi n8n

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

Esempio: articolo di news sul sito dell'organizzazione

Supponiamo che l'organizzazione abbia creato un flusso n8n che pubblica un articolo sul sito WordPress. In AI-Public inserisci allora solo un breve testo, ad esempio qualche frase su un incontro, progetto o annuncio pubblico. Con quel testo avvii il flusso in n8n.

Il flusso n8n può poi, ad esempio:

prendere dal breve testo una versione concisa da utilizzare come bozza con una node LLM e un prompt adatto al tono dell'organizzazione;
far creare una illustrazione adeguata con una seconda node LLM, ad esempio nei colori del brand e in uno stile illustrativo riconoscibile;
preparare o pubblicare l'articolo sul sito WordPress insieme al testo e all'immagine.

Così AI-Public e n8n lavorano insieme: in AI-Public l'utente sceglie il flusso di lavoro e inserisce le informazioni necessarie. n8n esegue quindi i passaggi automatizzati e garantisce che l'articolo sia pubblicato correttamente sul sito.

Cosa fa questa integrazione?

Avvii un flusso n8n dall'overview del flusso di lavoro. Sono obbligatori solo la webhook di produzione, POST e l'autenticazione header. Campi e risposte da n8n sono opzionali e possono essere impostati indipendentemente l'uno dall'altro.

Se il flusso di lavoro non ha campi, la webhook viene richiamata subito.
Se il flusso di lavoro ha campi, prima si apre un modulo. L'utente compila i campi e avvia quindi il flusso con il pulsante.
I valori compilati vengono inviati come JSON in una POST alla webhook n8n.
Senza risposte, AI-Public conferma solo che il flusso è stato avviato e prosegue in n8n. La finestra non mostra uno spinner e può essere chiusa immediatamente.
Se questa opzione è abilitata durante la registrazione, il flusso può inviare indietro fasi intermedie o la fine.
Se l'approvazione durante la registrazione è abilitata, l'utente può scegliere direttamente in AI-Public. n8n proseguirà poi dalla fase in attesa.

Creare flusso n8n in AI-Public

Un administrator registra il flusso come segue:

Vai a Assistenti.
Apri Flussi di lavoro.
Seleziona Nuovo flusso n8n.
Inserisci il nome del flusso e l'URL di produzione n8n.
Imposta Header authentication con un nome header e un valore header secret.
Spunta sotto Risposte da n8n solo le parti realmente implementate in questo flusso n8n: avanzamento, approvazione e/o fine del flusso.
Aggiungi eventualmente i campi che devono essere inviati nel POST.
Salva il flusso.

Tutte e tre le opzioni di ritorno sono disattivate di default. Se in seguito aggiungi callbacks o un passaggio di approvazione in n8n, aggiorna anche la registrazione in AI-Public. La dialog è quindi in grado di mostrare solo una conferma di avvio o di attendere segnali successivi.

Campi

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

Creazione di flusso compatibile in n8n

Crea in n8n un nuovo flusso di lavoro.
Aggiungi come prima node una Webhook.
Dai a questa node esattamente il nome Start workflow. Le espressioni di esempio qui sotto usano questo nome.
Imposta HTTP Method su POST.
Scegli Authentication: Header Auth e usa lo stesso nome header e lo stesso valore segreto usati in AI-Public.
Imposta Respond o Response Mode su Immediately.
Copia la Production URL nel campo n8n production URL in AI-Public. Non utilizzare l'URL di test con /webhook-test/.
Attiva il flusso.

I dati ricevuti sono sotto body; i dati di integrazione tecnica sono sotto body.integration. Non rimuoverli in un nodo Edit Fields, Set o Code.

Esempio del JSON body

Se definisci campi con i nomi prompt, cliente, target, e data, n8n riceverà ad esempio questo JSON body. AI-Public aggiunge automaticamente l'oggetto integration.

{
  "prompt": "Fai un breve riassunto della richiesta.",
  "cliente": "Organizzazione di Esempio",
  "target": ["residenti", "dipendenti"],
  "data": "2026-09-22",
  "integration": {
    "runId": "chat-document-id",
    "tenant": "default",
    "callbackUrl": "https://europe-west1-ai-public-pro.cloudfunctions.net/n8nWorkflowCallback",
    "callbackToken": "token-temporaneo-perquesta-esecuzione"
  }
}

Il callbacktoken è associato a una singola esecuzione. Non salvarlo nei log, in configurazioni fisse o in altri sistemi.

Opzionale: invio di avanzamento e completamento

AI-Public può mostrare solo ciò che restituisce n8n. Usa questi callback solo se durante la registrazione hai abilitato Segnala progresso intermedio e/o Segnala la fine del flusso di lavoro.

Configura ciascun nodo callback come segue:

Scegli Method: POST.

Clicca su URL su Expression e incolla:

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

Scegli Authentication: None.
Attiva Send Headers e aggiungi le seguenti intestazioni.
Attiva Send Body e scegli Body Content Type: JSON e Specify Body: Using JSON.

Usa queste intestazioni:

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

Per esempio, invia questo messaggio quando inizia una fase:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "document-maken-start",
  "type": "progress",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "document_maken",
    "label": "Creare documento"
  },
  "message": "Il documento è in fase di creazione."
}

Per ogni evento nella stessa esecuzione usa un unico eventId.
Usa una chiara label italiana per step.label; questo testo viene mostrato nell'app.
Se hai abilitato Segnala la fine del flusso di lavoro, invia sempre alla fine type: "completed", type: "failed" o type: "rejected".
Se presente, aggiungi un oggetto output con il risultato per completed.
Per failed invia un messaggio di errore comprensibile. L'esecuzione si ferma anche nell'app.

Opzionale: richiedere approvazione nell'app

Usa una node n8n Wait con On Webhook Call quando il flusso può proseguire solo dopo una scelta. Invia prima della Wait node un callback con type: "approval_required":

Configura la Wait node su Resume: On Webhook Call, HTTP Method: POST e Authentication: Header Auth. Seleziona la stessa credenziale Header Auth usata per Start workflow. Aggiungi dopo Wait una node Switch e controlla in essa {{ $json.body.decision }}.

{
  "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": "Controllo documento"
  },
  "approval": {
    "question": "La workflow può proseguire?",
    "context": "Controlla prima il documento generato.",
    "resumeUrl": "{{ $execution.resumeUrl }}",
    "choices": [
      { "value": "approve", "label": "Confermare" },
      { "value": "reject", "label": "Rifiutare" }
    ]
  }
}

L'utente vede le scelte nella finestra di esecuzione. Dopo una scelta, la Wait node riceve tra l'altro decision. Usa poi, ad esempio, una node Switch per determinare il flusso successivo.

Un valore di scelta può contenere solo lettere, cifre, _ e -; l'etichetta può contenere testo leggibile.

Impostare l'URL di callback di produzione

L'URL di callback di produzione per AI-Public è:

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

Non incollare questo URL come testo fisso in ogni node callback. Scegli nel campo URL della node HTTP Request Expression e usa:

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

AI-Public fornisce quindi automaticamente l'URL di produzione corretto ad ogni avvio. L'URL fisso sopra va usato durante i test per verificare che l'espressione punti ad AI-Public e non ad AI-School o AI-Corporate.

Le callable triggerCustomN8nWorkflow, triggerN8nWorkflow e resumeN8nWorkflow sono richiamate dall'app stessa. Non è necessario impostarle in n8n.

Gestione degli errori

Invia errori attesi tramite una callback di tipo failed. Per errori non previsti nei nodi, crea inoltre un flusso di errore centrale:

Crea un nuovo flusso con un nodo Error Trigger.
Aggiungi poi un nodo HTTP Request con Method: POST.

Compila in URL questa URL di produzione fissa:

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

Scegli Authentication: None e aggiungi l'header n8n-handihow-name con il valore segreto predefinito dell'amministratore della piattaforma.
Scegli un body JSON e incolla:

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

Abilita il Flusso di Errore.
Apri le impostazioni del flusso normale e selezionalo come Errore Workflow.

Invia subito dopo Start workflow almeno una callback con executionId: "{{ $execution.id }}". Solo così AI-Public può associare un errore inaspettato all’esecuzione corretta.

Limiti importanti

Sono supportati solo trigger webhook.
Sono supportati solo URL di webhook di produzione.
Gli URL di test webhook con /webhook-test/ sono rifiutati.
È supportato solo POST.
È supportata solo l’autenticazione generica tramite header.
Il valore dell’header è trattato come segreto dall’applicazione.
I token di callback e gli URL di resume sono elaborati solo lato server e non sono disponibili direttamente agli utenti.
Il tenant è determinato lato server dall’utente loggato, non da un valore che il browser invia.

Risoluzione dei problemi

404 o webhook non registrata: attiva il flusso in n8n e usa l’URL di produzione.
Errore di autenticazione: verifica che nome header e valore siano esatti in entrambi i sistemi.
Dati mancanti: verifica che i nomi dei campi nell’app siano coerenti con le chiavi attese da n8n.
Nessuna richiesta in n8n: controlla che il flusso inizi con un webhook trigger e usi POST.
La finestra di esecuzione continua a girare: se hai abilitato Segnala la fine del flusso di lavoro, controlla se n8n invia una callback finale completed, failed o rejected. Se non ti aspetti risposte, disattiva tutte e tre le opzioni nella registrazione.
Nessuna visibilità di avanzamento: verifica se in registrazione è attivato Segnala progresso intermedio, o se l’oggetto integration è conservato e se ogni callback ha un eventId univoco.
Pulsanti di approvazione non funzionano: controlla la Wait node, resumeUrl, l’autenticazione header e i caratteri ammessi in choices[].value.

Esempio: articolo di news sul sito dell'organizzazione​

Cosa fa questa integrazione?​

Creare flusso n8n in AI-Public​

Campi​

Creazione di flusso compatibile in n8n​

Esempio del JSON body​

Opzionale: invio di avanzamento e completamento​

Opzionale: richiedere approvazione nell'app​

Impostare l'URL di callback di produzione​

Gestione degli errori​

Limiti importanti​

Risoluzione dei problemi​