workflow n8n

AI-Corporate può avviare workflow n8n tramite un webhook di produzione. Questo è utile quando vuoi avviare un processo automatizzato al di fuori di AI-Corporate, ad esempio la creazione di un’attività, l’aggiornamento di un record CRM, l’avvio di un flusso di reportistica o l’inoltro dei dati di un modulo a un altro sistema.

Esempio: articolo di news sul sito aziendale

Supponiamo che l’organizzazione abbia creato un workflow n8n che pubblica un articolo di news sul sito WordPress dell’azienda. In AI-Corporate compili solo un breve testo, ad esempio poche frasi su un caso cliente, un evento o un traguardo interno. Con quel testo avvii il workflow in n8n.

Il workflow n8n può poi, per esempio:

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

Così AI-Corporate e n8n collaborano: in AI-Corporate l’utente sceglie il workflow e inserisce le informazioni necessarie. n8n esegue poi i passaggi automatizzati e fa sì che l’articolo di news 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 feedback da n8n sono opzionali e possono essere configurati indipendentemente l’uno dall’altro.

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 feedback, AI-Corporate conferma solo che il workflow è stato avviato e prosegue in n8n. La finestra non mostra alcuno spinner e può essere chiusa subito.
Se attivato in fase di registrazione, il workflow può inviare ad AI-Corporate passaggi intermedi o l’esito finale.
Se l’approvazione è stata attivata in fase di registrazione, l’utente può fare una scelta direttamente in AI-Corporate. n8n riprende quindi dal passaggio in attesa.

Creare un workflow n8n in AI-Corporate

Un amministratore registra il workflow come segue:

Vai su Assistenti.
Apri la scheda Assistenti workflow.
Nella card in alto fai clic su Nuovo workflow e scegli workflow n8n.
Compila il nome del workflow e l’URL di produzione n8n.
Configura Header authentication con un nome header e un valore header segreto.
In Feedback da n8n seleziona solo le parti che sono effettivamente costruite in questo workflow n8n: avanzamento, approvazione e/o fine del workflow.
Aggiungi eventualmente i campi che devono essere inclusi nella richiesta POST.
Salva il workflow.

Tutte e tre le opzioni di feedback sono disattivate per impostazione predefinita. Se in seguito aggiungi callback o un passaggio di approvazione in n8n, aggiorna anche la registrazione in AI-Corporate. In questo modo la finestra sa se deve mostrare solo una conferma di avvio o restare in attesa di ulteriori segnali.

Campi

I campi sono opzionali.
Ogni campo ha un nome campo e un tipo.
I tipi di campo supportati sono testo breve, testo lungo, numero, sì/no, data, scelta singola e scelte multiple.
Per Scelta singola e Scelte multiple aggiungi le opzioni disponibili. Scelta singola viene mostrata come elenco a discesa compatto; Scelte multiple 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

Crea un nuovo workflow in n8n.
Aggiungi come primo nodo un Webhook.
Dai a questo nodo 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 di AI-Corporate.
Imposta Respond o Response Mode su Immediately.
Copia la Production URL nel campo n8n productie-url in AI-Corporate. Non usare l’URL di test con /webhook-test/.
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, klantnaam, doelgroepen e datum, n8n riceverà per esempio questo body JSON. AI-Corporate aggiunge automaticamente l’oggetto integration.

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

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

Facoltativo: inviare avanzamento e completamento

AI-Corporate può mostrare solo ciò che n8n restituisce. Usa queste callback solo se in fase di registrazione hai attivato Segnala avanzamento intermedio e/o Segnala la fine del workflow.

Configura ogni nodo callback come segue:

Scegli Method: POST.

Clicca su Expression accanto a URL e incolla:

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

Scegli Authentication: None.
Attiva Send Headers e aggiungi le intestazioni qui sotto.
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 per esempio questo messaggio quando inizia un passaggio:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "documento-creato-avviato",
  "type": "progress",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "document_maken",
    "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 verrà 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 failed invia un messaggio di errore comprensibile. In questo caso l’esecuzione si interrompe anche nell’app.

Facoltativo: chiedere approvazione nell’app

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

Configura il nodo Wait su Resume: On Webhook Call, HTTP Method: POST e Authentication: Header Auth. Seleziona la stessa credenziale Header Auth usata per Start workflow. Aggiungi dopo il nodo Wait 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": "controle_document",
    "label": "Controllo documento"
  },
  "approval": {
    "question": "Il workflow può continuare?",
    "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, per 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-Corporate è:

https://europe-west1-ai-corporate.cloudfunctions.net/n8nWorkflowCallback

Non incollare questo URL come testo fisso in ogni nodo callback. Nel campo URL del nodo HTTP Request scegli Expression e usa:

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

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

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

Gestione degli errori

Invia gli errori previsti con una callback di tipo failed. Per gli errori imprevisti dei nodi, crea inoltre un Error Workflow centrale:

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

Nel campo URL inserisci questo URL di produzione fisso:

https://europe-west1-ai-corporate.cloudfunctions.net/n8nWorkflowExecutionFailed

Scegli Authentication: None e aggiungi l’header n8n-handihow-name con il valore standard segreto 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 }}"
}

Attiva l’Error Workflow.
Apri le impostazioni del workflow normale e selezionalo in Error Workflow.

Subito dopo Start workflow invia almeno una callback con executionId: "{{ $execution.id }}". Solo così AI-Corporate 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 callbacktoken e gli URL di resume vengono elaborati solo lato server e non sono disponibili direttamente agli utenti.
Il tenant viene determinato lato server in base all’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 header e valore coincidano esattamente 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 continua a girare: se hai attivato Segnala la fine del workflow, controlla che n8n invii una callback finale completed, failed o rejected. Se non ti aspetti alcun feedback, 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.

Esempio: articolo di news sul sito aziendale​

Cosa fa questa integrazione?​

Creare un workflow n8n in AI-Corporate​

Campi​

Creare un workflow compatibile in n8n​

Esempio del body JSON​

Facoltativo: inviare avanzamento e completamento​

Facoltativo: chiedere approvazione nell’app​

Impostare l’URL di callback di produzione​

Gestione degli errori​

Limitazioni importanti​

Risoluzione dei problemi​