Vai al contenuto principale

workflow n8n

AI-Public può avviare workflow n8n tramite un webhook di produzione. Questo è utile quando vuoi avviare un processo automatizzato al di fuori di AI-Public, 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 web dell’organizzazione​

Supponiamo che l’organizzazione abbia creato un workflow n8n che pubblica un articolo di notizie sul sito WordPress. In AI-Public inserisci solo un breve testo, ad esempio poche frasi su un incontro, un progetto o un annuncio pubblico. Con quel testo avvii il workflow in n8n.

Il workflow n8n può quindi, ad esempio:

  1. Trasformare il breve testo in una bozza pulita con un nodo LLM e un prompt adatto al tono dell’organizzazione.
  2. Creare un’illustrazione appropriata con un secondo nodo LLM, ad esempio nei colori della casa 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-Public e n8n lavorano insieme: in AI-Public 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 ordinatamente sul sito web.

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 le notifiche di ritorno da n8n sono opzionali e possono essere configurati indipendentemente tra loro.

  • Se il workflow non ha campi, il webhook viene chiamato subito.
  • Se il workflow ha 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 notifiche di ritorno, AI-Public conferma solo che il workflow è stato avviato e prosegue in n8n. La finestra non mostra uno spinner e può essere chiusa subito.
  • Se questa opzione è stata attivata nella registrazione, il workflow può inviare ad AI-Public passaggi intermedi o il risultato finale.
  • Se l’approvazione è stata attivata nella registrazione, l’utente può fare una scelta direttamente in AI-Public. n8n prosegue poi dal passaggio in attesa.

Creare un workflow n8n in AI-Public​

Un amministratore registra il workflow nel modo seguente:

  1. Vai a Assistenti.
  2. Apri la scheda Assistenti workflow.
  3. Nella scheda in alto fai clic su Nuovo workflow e scegli workflow n8n.
  4. Compila il nome del workflow e l’URL di produzione n8n.
  5. Configura Header authentication con un nome dell’header e un valore segreto dell’header.
  6. In Notifiche di ritorno da n8n seleziona solo le parti che sono effettivamente state costruite 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 notifica di ritorno sono disattivate per impostazione predefinita. Se in un secondo momento aggiungi callback o un passaggio di approvazione in n8n, aggiorna anche la registrazione in AI-Public. In questo modo la dialog sa se deve mostrare solo una conferma di avvio o continuare ad attendere altri 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 scelta viene mostrata come elenco a discesa 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. Assegna a questo nodo esattamente il nome Start workflow. Le espressioni di esempio qui sotto usano questo nome.
  4. Imposta HTTP Method su POST.
  5. Scegli Authentication: Header Auth e usa lo stesso nome dell’header e lo stesso valore segreto di AI-Public.
  6. Imposta Respond o Response Mode su Immediately.
  7. Copia la Production URL nel campo URL di produzione n8n in AI-Public. Non usare l’URL di test con /webhook-test/.
  8. Attiva il workflow.

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

Esempio del body JSON​

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

{
  "prompt": "Crea un breve riassunto della richiesta.",
  "nomecliente": "Organizzazione di esempio",
  "gruppi_target": ["cittadini", "collaboratori"],
  "data": "2026-09-22",
  "integration": {
    "runId": "chat-document-id",
    "tenant": "default",
    "callbackUrl": "https://europe-west1-ai-public-pro.cloudfunctions.net/n8nWorkflowCallback",
    "callbackToken": "token-temporaneo-per-questa-esecuzione"
  }
}

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

Opzionale: inviare avanzamento e completamento​

AI-Public può mostrare solo ciò che n8n comunica. Usa questi callback solo se nella registrazione hai attivato Segnala avanzamento intermedio e/o Segnala la fine del workflow.

Configura ciascun nodo di callback come segue:

  1. Scegli Method: POST.

  2. Fai clic su Expression accanto a URL e incolla:

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

  3. Scegli Authentication: None.

  4. Attiva Send Headers e aggiungi le intestazioni seguenti.

  5. 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

Invia ad esempio questo messaggio quando inizia un passaggio:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "creazione-documento-avviata",
  "type": "progress",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "creazione_documento",
    "label": "Creazione documento"
  },
  "message": "Il documento viene creato."
}
  • Usa un eventId univoco per ogni evento all’interno della stessa esecuzione.
  • Usa un chiaro step.label in italiano; questo testo viene mostrato nell’app.
  • Se hai attivato Segnala la fine del workflow, invia sempre alla fine type: "completed", type: "failed" o type: "rejected".
  • In completed puoi eventualmente aggiungere un oggetto output con il risultato.
  • In caso di failed, invia un messaggio di errore comprensibile. L’esecuzione si fermerà anche nell’app.

Opzionale: chiedere approvazione nell’app​

Usa un nodo Wait di n8n con On Webhook Call quando il workflow può proseguire solo dopo una scelta. Prima del nodo Wait invia un callback con type: "approval_required":

Configura il nodo Wait su Resume: On Webhook Call, HTTP Method: POST e Authentication: Header Auth. Seleziona le stesse credenziali Header Auth di Start workflow. Dopo il nodo Wait aggiungi un nodo Switch e controlla {{ $json.body.decision }}.

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "controllo-documento",
  "type": "approval_required",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "controllo_documento",
    "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" }
    ]
  }
}

L’utente vede le scelte nella finestra di esecuzione. Dopo una scelta, il nodo Wait riceve tra le altre cose decision. Usa poi ad esempio un nodo Switch per determinare il seguito corretto.

Un valore di scelta può contenere solo lettere, numeri, _ e -. L’etichetta può invece contenere testo normale 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 nodo di callback. Nel campo URL del nodo HTTP Request scegli Expression e usa:

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

In questo modo AI-Public fornisce automaticamente a ogni avvio l’URL di produzione corretto. L’URL fisso qui sopra serve per verificare durante i test che l’espressione punti ad AI-Public e non ad AI-School o AI-Corporate.

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

Gestione degli errori​

Invia gli errori previsti con un callback di tipo failed. Per errori di nodo imprevisti crea inoltre un Error Workflow centrale:

  1. Crea un nuovo workflow con un nodo Error Trigger.

  2. Aggiungi poi un nodo HTTP Request con Method: POST.

  3. Inserisci nel campo URL questo URL fisso di produzione:

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

  4. Scegli Authentication: None e aggiungi l’header n8n-handihow-name con il valore segreto predefinito dell’amministratore della piattaforma.

  5. 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 }}"
}
  1. Attiva l’Error Workflow.
  2. Apri le impostazioni del workflow normale e selezionalo in Error Workflow.

Subito dopo Start workflow invia almeno un callback con executionId: "{{ $execution.id }}". Solo così AI-Public può collegare un errore imprevisto all’esecuzione corretta.

Limitazioni importanti​

  • Sono supportati solo trigger webhook.
  • Sono supportati solo URL webhook di produzione.
  • Gli URL webhook di test con /webhook-test/ vengono rifiutati.
  • È supportato solo POST.
  • È supportata solo l’autenticazione generica tramite header.
  • Il valore dell’header viene trattato come segreto nell’applicazione.
  • I token di callback e gli URL di resume vengono elaborati solo lato server e non sono direttamente disponibili per gli utenti.
  • Il tenant viene determinato lato server dall’utente connesso, 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 e valore dell’header siano identici in entrambi i sistemi.
  • Dati mancanti: controlla che i nomi dei campi nell’applicazione corrispondano alle key che n8n si aspetta.
  • Nessuna richiesta in n8n: controlla che il workflow inizi con un trigger webhook e usi POST.
  • La finestra di esecuzione rimane aperta: se hai attivato Segnala la fine del workflow, controlla che n8n invii un ultimo callback completed, failed o rejected. Se non ti aspetti notifiche di ritorno, disattiva tutte e tre le opzioni nella registrazione.
  • Nessun avanzamento visibile: controlla che Segnala 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.

In questa pagina