flussi n8n

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

Esempio: articolo di notizia sul sito aziendale

Supponiamo che l’organizzazione abbia creato un flusso di lavoro n8n che pubblica un articolo sul sito WordPress dell’azienda. In AI-Corporate inserisci allora solo un breve testo, ad esempio un paio di frasi su un caso cliente, un evento o una tappa interna. Con quel testo avvii il flusso di lavoro in n8n.

Il flusso di lavoro n8n può poi, ad esempio:

1. Dal testo breve creare una bozza ben formattata con un nodo LLM e una prompt adatta al tono dell’organizzazione.
2. Far generare un’illustrazione appropriata con un secondo nodo LLM, ad esempio nei colori del brand e in uno stile illustrativo riconoscibile.
3. Preparare o pubblicare il testo e l’immagine come post del blog sul sito WordPress.

Ecco come AI-Corporate e n8n lavorano insieme: in AI-Corporate l’utente seleziona il flusso di lavoro e inserisce le informazioni necessarie. Successivamente n8n esegue i passi automatizzati e si assicura che l’articolo appaia correttamente sul sito.

Cosa fa questa integrazione?

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

• Se il flusso di lavoro non ha campi, il webhook viene richiamato immediatamente.
• Se il flusso di lavoro ha campi, prima si apre un modulo. L’utente compila i campi e avvia poi il flusso con il pulsante.
• I valori compilati sono inviati come JSON in una richiesta POST al webhook di n8n.
• Senza risposte, AI-Corporate conferma solo che il flusso è stato avviato e procede in n8n. La finestra non mostra uno spinner e può essere chiusa immediatamente.
• Se abilitato in fase di registrazione, il flusso può inviare indietro fasi intermedie o la fine ad AI-Corporate.
• Se l’approvazione è abilitata in fase di registrazione, l’utente può scegliere direttamente in AI-Corporate. n8n prosegue quindi dalla fase in attesa.

Creare un flusso di lavoro n8n in AI-Corporate

Un amministratore registra il flusso di lavoro come segue:

1. Vai su Assistenti.
2. Apri Flussi di lavoro.
3. Seleziona Nuovo flusso di lavoro n8n.
4. Inserisci il nome del flusso di lavoro e l’URL di produzione di n8n.
5. Imposta Autenticazione Header con un nome di header e un valore header segreto.
6. Seleziona sotto Risposte da n8n solo le parti realmente costruite in questo flusso di lavoro n8n: avanzamento, approvazione e/o la fine del flusso.
7. Aggiungi eventualmente i campi che devono essere inviati nel POST-request.
8. Salva il flusso di lavoro.

Tutte e tre le opzioni di risposta sono disabilitate di default. Se in seguito aggiungi callback o un passaggio di approvazione in n8n, aggiorna anche l’iscrizione in AI-Corporate. Il dialogo saprà quindi se mostra solo una conferma di avvio o se deve attendere ulteriori segnali.

Campi

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

Creare un flusso di lavoro compatibile in n8n

1. Crea in n8n un nuovo flusso di lavoro.
2. Aggiungi come primo nodo un Webhook.
3. Dai 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 usati in AI-Corporate.
6. Imposta Respond o Response Mode su Immediately.
7. Copia la Production URL nel campo n8n production-url in AI-Corporate. Non usare l’URL di test con /webhook-test/.
8. Attiva il flusso di lavoro.

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

Esempio di body JSON

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

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

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

Opzionale: invio di avanzamento e completamento

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

Configura ogni node callback come segue:

1. Scegli Method: POST.

2. Nell’URL seleziona Expression 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

Ad esempio invia questo messaggio quando una fase inizia:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "document-creation-started",
  "type": "progress",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "document_creation",
    "label": "Creazione del documento"
  },
  "message": "Il documento viene creato."
}

• Per ogni evento all’interno della stessa esecuzione usa un unico eventId.
• Usa una chiara etichetta in olandese step.label; questo testo viene mostrato nell’app.
• Se hai abilitato Segnala fine del flusso di lavoro, invia sempre in chiusura type: "completed", type: "failed" o type: "rejected".
• Se hai completed, allega eventualmente un oggetto output con il risultato.
• In caso di failed invia un messaggio di errore comprensibile. L’esecuzione si ferma anche nell’app.

Opzionale: richiedere approvazione nell’app

Usa un nodo n8n Wait con On Webhook Call quando il flusso 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 di Start workflow. Aggiungi dopo il nodo Wait un nodo Switch e verifica {{ $json.body.decision }}.

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "document-check",
  "type": "approval_required",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "document_check",
    "label": "Controllo del documento"
  },
  "approval": {
    "question": "Vuoi continuare con la workflow?",
    "context": "Verifica 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 fornisce tra l’altro decision. Usa poi, ad esempio, un nodo Switch per determinare la sequenza successiva.

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-Corporate è:

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

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

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

AI-Corporate fornirà così, ad ogni avvio, automaticamente la giusta URL di produzione. L’URL fisso sopra viene usato durante i test per verificare che l’espressione punti ad AI-Corporate e non ad AI-School o AI-Public.

Le callable triggerCustomN8nWorkflow, triggerN8nWorkflow e resumeN8nWorkflow sono richiamate dall’app stessa. Non è necessario impostare questi URL in n8n.

Gestione degli errori

Invia errori attesi tramite un callback di tipo failed. Per errori di nodo imprevisti crea anche un flusso di errore centrale:

1. Crea un nuovo flusso di lavoro con un nodo Error Trigger.

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

3. Compila l’URL con questo URL di produzione fisso:

   https://europe-west1-ai-corporate.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 corpo JSON e incolla:

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

6. Attiva il Flusso di Errore.
7. Apri le impostazioni del flusso di lavoro normale e seleziona questo come Error Workflow.

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

Limitazioni importanti

• Sono supportati solo trigger webhook.
• Sono supportati solo URL webhook di produzione.
• I webhook di test con /webhook-test/ sono rifiutati.
• È supportato solo POST.
• È supportata solo l’autenticazione header generica.
• Il valore dell’header è trattato come segreto dall’app.
• I token di callback e gli URL di resume sono elaborati solo lato server e non sono accessibili direttamente agli 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 dell’header e il valore siano identici in entrambi i sistemi.
• Dati mancanti: verifica che i nomi dei campi nell’app corrispondano alle chiavi attese da n8n.
• Nessuna richiesta in n8n: verifica che il flusso inizi con un webhook trigger e usi POST.
• La finestra di esecuzione resta in attesa: se hai abilitato la chiusura del flusso con una risposta, verifica se n8n invia un ultimo completed, failed o rejected callback. Se non ti aspettavi risposte, disattiva tutte e tre le opzioni in registrazione.
• Nessun avanzamento visibile: verifica se in registrazione è attiva l’opzione Segnala avanzamento intermedio, oppure se l’oggetto integration è mantenuto e se ogni callback ha un eventId unico.
• Pulsanti di approvazione non funzionano: controlla il nodo Wait, l’URL di resume, l’autenticazione dell’header e i caratteri ammessi in choices[].value.