Glossario N8N: tutti i termini da conoscere per lavorare con N8N

Il Glossario N8N è la scorciatoia per orientarti tra termini, nodi e pratiche operative che trasformano semplici automazioni in processi affidabili. Se ti occupi di marketing e vuoi migliorare la produttività senza scrivere codice complesso, conoscere la terminologia n8n e il vocabolario dei nodi n8n ti aiuta a progettare workflow chiari, a connettere API e basi dati con sicurezza, e a scalare le tue integrazioni in modo governato. In questa guida troverai definizioni rapide, contesto d’uso e best practice applicative su nodi trigger di n8n (webhook, cron, polling), espressioni $json e variabili in n8n, paired items e mapping dati, differenza tra dati JSON e binari in n8n, gestione credenziali OAuth2 e API key su n8n, queue mode con Redis/BullMQ in n8n, execute workflow e sub‑workflow, split in batches e item lists, continue on fail ed error workflow, oltre a note su editor UI e backend di n8n e deploy self‑hosted con Docker per n8n. È un riferimento pratico che puoi usare ogni giorno per progettare, testare e mettere in produzione i tuoi flussi.

📚 Nuovo a n8n? Parti dalla guida completa: cos’è n8n e come funziona.

[IMG: panoramica dell’editor con un workflow etichettato e nodi documentati]

Workflow, esecuzioni e modalità (manuale, test, attivo)

Un workflow è la sequenza di nodi (trigger, azioni, utilità, codice) che trasforma un evento in un risultato. In fase di sviluppo puoi avviarlo manualmente, testare singoli rami e “pinnare” dati di prova, quindi attivarlo per esecuzioni automatiche.

Modalità di esecuzione:
Manuale/test: ideale per debug step‑by‑step, con data pinning per riprodurre casi reali.
Attivo: il workflow reagisce a trigger (webhook, cron, polling) ed entra in esercizio.
Versioning dei workflow in n8n: mantieni copie e note di rilascio per capire quando e perché un flusso è cambiato; è fondamentale per audit e rollback.
Naming e documentazione: assegna un nome descrittivo al workflow, aggiungi note inline e un changelog; quando l’organizzazione cresce, queste informazioni fanno la differenza.

Consiglio pratico: parti da un MVP per un singolo canale (es. acquisizione lead da una form) e poi estendi. Un glossario di progetto conterminologia n8n condivisa riduce gli errori di comunicazione tra marketing e IT.

[IMG: pannello esecuzione con stato, durata e output di esempio]

Item, JSON e dati binari: formati, trasformazioni e “paired items”

In n8n tutto scorre come items, oggetti con payload JSON e, quando serve, dati binari (file, immagini). Sapere come trasformarli rende i flussi più robusti.

JSON vs binari:
JSON: campi strutturati, numeri, stringhe, array, oggetti.
Binari: file allegati all’item, gestiti separatamente per non “gonfiare” il JSON.
Paired items e mapping dati: quando una trasformazione genera più elementi o li riallinea, n8n mantiene relazioni interne tra item (“paired items”) per non perdere il collegamento logico. In termini pratici, usa nodi di trasformazione in modo coerente (Split In Batches, Item Lists) e riduci “salti” inattesi per preservare il pairing.
Sintassi di espressione:
Accedere ai campi: {{$json[“email”]}} o {{$json.name}}
Riferirsi a più elementi: $items()
Tempo e variabili: $now per timestamp, $env per variabili d’ambiente
Binari: $binary per riferimenti a file allegati

Pattern utile: normalizza sempre i nomi dei campi a inizio flusso (Set/Code) così l’espressione editor resta leggibile e consistente.

[IMG: nodo Set che mappa campi da input esterno a JSON pulito]

Input/Output dei nodi, mapping dei campi e propagazione dei dati

Ogni nodo riceve items, esegue un’operazione e produce nuovi items. Il mapping dei campi garantisce che i dati giusti raggiungano il nodo giusto.

Set: definisce/riscrive campi con valori statici o dinamici.
If / Switch: smista in rami in base a condizioni (es. lead “Enterprise” vs “SMB”).
Merge: riunisce rami o unisce dataset (per posizione, chiave, o concatenazione).
Item Lists: manipola array (splitIntoItems per “esplodere” una lista in items singoli).
Split In Batches: elabora grandi volumi a lotti (batchSize) per non superare limiti API.

Esempio Item Lists (operazione esatta):

{
  "name": "Split Array",
  "type": "n8n-nodes-base.itemLists",
  "typeVersion": 1,
  "parameters": {
    "operation": "splitIntoItems",
    "property": "results"
  }
}

Esempio Split In Batches (parametro chiave):

{
  "name": "Batch Loop",
  "type": "n8n-nodes-base.splitInBatches",
  "typeVersion": 1,
  "parameters": {
    "batchSize": 10
  }
}

Best practice: mantieni coerenti i nomi dei campi tra i rami e usa Merge per riallineare gli output. Così l’analisi degli errori è più semplice e l’audit più chiaro.

[IMG: flusso con If → due rami → Merge by position → output unico]

Nodi trigger: Webhook, Schedule/Cron ed eventi

I nodi trigger avviano il workflow.

Webhook Trigger: espone un endpoint HTTP per ricevere eventi (es. form, e‑commerce, webhook partner).
Parametri esatti utili:
- path (es. “incoming-data”)
- methods (es. [“POST”])
- responseMode: “onReceived” oppure “lastNode”
- responseData: { “statusCode”: 200, “body”: “Webhook received successfully” }
Esempio:

{ "path": "incoming-data", "methods": ["POST"], "responseMode": "onReceived", "responseData": { "statusCode": 200, "body": "Webhook received successfully" } }

Suggerimento: usa responseMode=”onReceived” per rispondere subito e proseguire l’elaborazione in background.
Schedule/Cron: pianifica esecuzioni (report giornalieri, sincronizzazioni orarie).
Polling/Event: quando il connettore supporta verifiche periodiche o subscription ad eventi.

Integrare presto un nodo di validazione (If/Code) dopo il trigger evita chiamate errate a servizi esterni e rende il flusso più resiliente.

[IMG: pannello Webhook con URL pubblico e metodo POST abilitato]

Nodi di trasformazione e controllo: Set, IF, Merge, Split In Batches, Item Lists, Wait

Questi nodi compongono la logica “no‑code”:

Set: crea/aggiorna campi (es. normalizzare “firstName” e “lastName”).
IF/Switch: filtra o indirizza item in base a regole di business.
Merge: unisce rami; by position per sequenze, by key per join.
Split In Batches: evita rate limit elaborando in lotti (batchSize).
Item Lists: splitIntoItems per trasformare un array in più items; utile con API che restituiscono liste.
Wait: sospende fino a un orario o evento (utile per sequenze temporizzate).

Pattern tipico marketing: “import lead → deduplica → arricchisci (arricchimento esterno) → qualifica (If) → invia a CRM → notifica Slack”.

[IMG: canvas con Set → If → Item Lists → Split In Batches → Merge]

Nodi di codice: Code (ex Function), snippet utili e limiti

Quando la logica supera il drag‑and‑drop, entra in gioco il Code Node (ex Function Node): scrive JavaScript per validazioni, mapping complessi, formattazioni.

Caratteristiche:
functionCode con trasformazioni sugli items
Esecuzione “per item” o “una volta su tutti”
Esempio: normalizzazione email e aggiunta correlationId

  const items = $input.all();
  const out = items.map((i, idx) => {
    const email = (i.json.email || '').trim().toLowerCase();
    const correlationId = `${$now}_${idx}`;
    return { json: { ...i.json, email, correlationId } };
  });
  return out;

Limite salutare: prima prova con nodi di utilità; il codice rende potente ma meno leggibile. Documenta sempre le trasformazioni importanti.

[IMG: editor del Code Node con snippet e output di test]

Composizione modulare: Execute Workflow e sub‑workflow riutilizzabili

Spezza flussi complessi in moduli riutilizzabili con Execute Workflow:

Parametri esatti tipici:
workflowId: “123”
waitForCompletion: true
inputs: passaggio di dati al sub‑workflow
Esempio:

  {
    "name": "Execute Workflow",
    "type": "n8n-nodes-base.executeWorkflow",
    "typeVersion": 1,
    "parameters": {
      "workflowId": "123",
      "waitForCompletion": true,
      "inputs": { "inputData": "={{ $json[\"data\"] }}" }
    }
  }

Vantaggi: riuso, test più semplice, e cicli di rilascio indipendenti (un sub‑workflow può evolvere con versioning dedicato).

[IMG: chiamata a un sub‑workflow “SanitizzaLead” con input dedicato]

Modelli di autenticazione e sicurezza: API Key, OAuth2, Basic e header personalizzati

L’HTTP Request node integra qualsiasi API. Parametri utili:

url, method, responseFormat (es. “json”), jsonParameters (true), bodyParametersJson, headerParametersUi (Authorization: Bearer …), options.bodyContentType (“json”).

Esempio:

{
  "name": "HTTP Request",
  "type": "n8n-nodes-base.httpRequest",
  "typeVersion": 1,
  "parameters": {
    "url": "https://api.example.com/leads",
    "method": "POST",
    "responseFormat": "json",
    "jsonParameters": true,
    "bodyParametersJson": {
      "email": "={{$json[\"email\"]}}",
      "source": "landing-2025"
    },
    "options": { "bodyContentType": "json" },
    "headerParametersUi": {
      "parameter": [
        { "name": "Authorization", "value": "Bearer {{$env.API_TOKEN}}" }
      ]
    }
  }
}

Credenziali OAuth2 e API key su n8n: sfrutta credenziali nel vault e referenziale per nome/ID; evita segreti hardcoded nei nodi.
Resource Locator e parametri dinamici: usa l’espression editor per costruire URL e payload; testali con dati reali.
Protezione dei segreti: variabili d’ambiente, cifratura nativa delle credenziali, e rotazione periodica.

[IMG: nodo HTTP Request con header Authorization e body JSON validato]

Governance, audit e gestione errori: Continue On Fail, Error Trigger, log e alert

Qualità operativa significa tracciare e reagire agli imprevisti.

continueOnFail (parametro esatto):

  {
    "name": "Some Node",
    "type": "n8n-nodes-base.httpRequest",
    "typeVersion": 1,
    "parameters": {
      "continueOnFail": true
    }
  }

Utile per passaggi non critici: il workflow non si interrompe.

Error Trigger: workflow dedicato che riceve errori dagli altri workflow e invia notifiche (email/Slack), oppure scrive eventi verso un SIEM tramite HTTP Request.
Audit trail per workflow di automazione: genera un correlationId nel primo nodo (Set/Code) e propagalo nei log/HTTP esterni insieme a workflowName e versione.
Monitoraggio e alert dei workflow: KPI di successo/fallimento, latenza, errori 4xx/5xx; al superamento soglie, alza un alert.

[IMG: flusso “Error Handler” con canale Slack e invio a endpoint di logging]

Architettura, queue mode e deploy: da test a produzione

Capire come “vive” n8n aiuta a scalare:

Editor UI e backend di n8n: interfaccia per disegnare/testare; il backend esegue i workflow.
Queue mode con Redis/BullMQ in n8n: architettura per distribuire esecuzioni su più worker; utile per carichi elevati o attività lente. Concettualmente, i trigger mettono job in coda, i worker li consumano rispettando priorità e concorrenza.
n8n Cloud vs deploy self‑hosted con Docker per n8n: il cloud accelera l’avvio; il self‑hosted offre controllo su rete, compliance e performance. Ricorda backup e strategia di aggiornamento.

Consiglio: separa ambienti (dev/staging/prod). Promuovi versioni testate e monitora dopo ogni rilascio per captare regressioni.

[IMG: diagramma con UI/Backend, Redis/BullMQ e più worker in parallelo]

Performance: paginazione, batch, gestione payload e limiti API

Per evitare colli di bottiglia:

Paginazione e Split In Batches: riduci la dimensione delle chiamate e controlla il ritmo con batchSize.
Rate limits: implementa backoff e jitter; riduci concorrenza sulle API critiche.
Payload: filtra i campi superflui (Set) e rimuovi allegati non necessari.
Retry consapevoli: ritenta solo errori transitori (timeout, 5xx); per 4xx mappa percorsi di recupero (If/Code).

Insight: registra i tempi dei nodi “lenti” e investi in caching o sub‑workflow dedicati. Spesso un refactor di mapping dati abbatte il tempo di esecuzione più di qualsiasi ottimizzazione micro.

[IMG: tabella con tempi medi per nodo e percentuali di errore per endpoint]

A–Z: mini‑vocabolario rapido

A–F: Active workflow, Authentication, Binary data, Credentials, Cron, Continue On Fail
G–P: HTTP Request, Execute Workflow, IF, Item Lists, JSON, Merge, Node, Paired items, Parameters
Q–Z: Queue mode, Resource Locator, Schedule, Static Data, Sub‑workflow, Trigger, Webhook, Worker

[IMG: scheda riassuntiva con le voci principali e riferimenti al workflow]

Quick Takeaways

Il vocabolario dei nodi n8n parte da trigger, azioni, utilità e codice: combinandoli costruisci automazioni robuste.
Il Webhook Trigger usa path, methods, responseMode e responseData per ingressi affidabili; HTTP Request unisce qualsiasi API con header e body JSON.
Gestisci trasformazioni con Set/If/Merge/Item Lists e controlla scalabilità con Split In Batches.
Riusa logica complessa con Execute Workflow (workflowId, waitForCompletion, inputs) e documenta ogni versione.
Sicurezza prima: credenziali nel vault, OAuth2 dove possibile, variabili d’ambiente e rotazione periodica.
Governance: correlationId, audit esterno, Error Trigger e alert proattivi.
Scala in queue mode con Redis/BullMQ e separa ambienti per rilasci sicuri.

Conclusione

Un glossario operativo rende n8n più accessibile e, soprattutto, più affidabile in produzione. Conoscere termini e parametri chiave — dal Webhook Trigger (path, methods, responseMode, responseData) all’HTTP Request (jsonParameters, responseFormat, bodyParametersJson, headerParametersUi), fino a Split In Batches, Item Lists e Execute Workflow (workflowId, waitForCompletion, inputs) — ti permette di costruire automazioni chiare e manutenibili. Integra fin da subito sicurezza e governance: vault delle credenziali, OAuth2, variabili d’ambiente, correlationId e Error Trigger con alert. Sul fronte performance, usa paginazione, batch e retry mirati per rispettare i rate limit. Se sei un marketer che vuole imparare ad usare n8n per migliorare la produttività, parti da un flusso concreto (lead, contenuti o report), etichetta bene i nodi, abilita audit e versioning, quindi misura tempi e tassi d’errore. In poche iterazioni, passerai da “automazioni sporadiche” a un sistema operativo su cui il team può contare.

FAQ

A cosa serve davvero questo Glossario N8N?
A chiarire la terminologia n8n e il vocabolario dei nodi n8n per progettare flussi comprensibili, testabili e conformi, riducendo errori e tempi di debug.
Come uso correttamente i nodi trigger di n8n (webhook, cron, polling)?
Il Webhook Trigger espone path, methods, responseMode e responseData per rispondere subito o al termine. Cron pianifica esecuzioni. I connettori polling verificano periodicamente nuovi eventi.
Quali sono le espressioni più utili?
{{$json}} per i campi del payload, $items() per liste, $now per timestamp e $env per variabili d’ambiente. Queste coprono la maggior parte dei casi di mapping.
Come gestisco credenziali e sicurezza?
Usa il vault credenziali, preferisci OAuth2 e definisci header in headerParametersUi (es. Authorization). Evita segreti hardcoded e applica rotazione periodica.
Come rendo affidabile un workflow complesso?
Dividilo in sub‑workflow con Execute Workflow (workflowId, waitForCompletion, inputs), monitora con Error Trigger e alert, gestisci batch/paginazione e usa continueOnFail solo dove tollerabile.

Hai un termine che vorresti aggiungere a questo Glossario N8N? Scrivilo nei commenti e condividi l’articolo con chi inizia ora con n8n: quale definizione ti ha sbloccato di più nel progettare il tuo prossimo workflow?