L’API di n8n spiegata: come gestire i workflow via codice

Vuoi portare l’automazione del tuo marketing a un livello superiore, orchestrando workflow, credenziali e ambienti… senza aprire l’editor? Con l’api n8n puoi farlo: l’API pubblica espone endpoint sicuri per creare e aggiornare workflow, controllare le esecuzioni, gestire tag e progetti, integrare CI/CD e perfino testare le chiamate con un API playground. In questa guida pratica uniamo documentazione ufficiale e best practice operative per aiutarti a scegliere quando usare l’API pubblica rispetto a un webhook in n8n, come autenticarti, come paginare in modo efficiente e come monitorare log ed errori.

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

In altre parole: passiamo dalla teoria all’operatività. Parleremo di API REST di n8n, endpoint per workflow su n8n, esecuzioni di n8n via richiesta HTTP, token di accesso per l’API di n8n e API playground n8n. Se sei un marketer che vuole risparmiare ore di lavoro con automazione avanzata e integrazione con sistemi esterni, troverai esempi curl per n8n, consigli su sicurezza e permessi nell’API di n8n, e un flusso end-to-end riusabile. L’obiettivo: usare l’api n8n in modo affidabile e produttivo, dal provisioning alla messa in produzione.

API pubblica vs Webhook vs nodi “API”: differenze e quando usarli

Per esporre o controllare automazioni “via codice” in n8n esistono tre approcci complementari, ciascuno con pro e contro.

API pubblica di n8n
Cosa fa: consente di gestire risorse interne (workflows, executions, credentials, tags, projects) con endpoint ufficiali. Ottima per provisioning di workflow, automazione CI/CD con n8n, gestione massiva e audit/monitoraggio a posteriori.
Quando usarla: gestione strutturale (crea/aggiorna/attiva workflow, consulta esecuzioni, applica tag, orchestri ambienti).
Webhook in n8n
Cosa fa: espone un endpoint HTTP personalizzato per avviare un workflow dall’esterno (tipicamente POST/GET) e rispondere via “Respond to Webhook”.
Quando usarlo: attivare una singola esecuzione “on demand” (ad esempio da un form, un ads webhook, un CRM) e costruire un “mini backend” API-like con logica marketing in tempo reale.
Nodi “API” (HTTP Request, GraphQL)
Cosa fanno: chiamano API esterne da dentro un workflow. Perfetti per integrazione con sistemi esterni, enrichment, sincronizzazioni, notifiche.
Quando usarli: consumo di API terze (CRM, ad platform, analytics, LLM…), orchestrazione dati e azioni.

Insight pratico: per “gestire i workflow via codice”, la rotta è combinare API pubblica (provisioning e governance), Webhook (trigger runtime) e HTTP Request (integrazioni esterne). Così separi nettermente la gestione delle risorse n8n dall’attivazione di flussi e dalla comunicazione con SaaS esterni, guadagnando sicurezza, tracciabilità e velocità.

Autenticazione, sicurezza e permessi: come proteggere l’API

L’API pubblica usa API key inviate nell’header X-N8N-API-KEY. Per creare una chiave:

In n8n vai su Settings > n8n API > Create an API key.
Imposta Label, Expiration e (Enterprise) Scopes.
Usa la chiave in ogni chiamata.

Esempio (n8n Cloud e self-hosted sono equivalenti a livello di header):

Header: X-N8N-API-KEY: YOURSECRETTOKEN

Buone pratiche per marketer e team:

Modalità di autenticazione supportate e gestione dei token in ambienti cloud/self-hosted
n8n Cloud: base URL tipico https://{instance}.app.n8n.cloud/api/v1.
Self-hosted: ://api/v1; l’API playground è disponibile solo self-hosted.
Principi di least privilege e rotazione credenziali
Enterprise: usa gli API Scopes per limitare l’accesso alle sole risorse necessarie.
Ruota le chiavi periodicamente e revoca immediatamente quelle non più necessarie.
Segreti e configurazioni sicure
Mantieni le chiavi fuori dai workflow JSON e gestiscile via secret manager o variabili d’ambiente nel tuo orchestratore CI/CD.
Controlli di accesso, audit trail, rete (IP allowlist, TLS), segregazione ambienti
Abilita TLS end-to-end.
In Cloud, consulta la lista IP per eventuali allowlist; on-prem, configura firewall/proxy.
Usa progetti e ambienti separati (dev/stage/prod) con processi di promozione.
Disabilitare l’API se non serve
Self-hosted: N8NPUBLICAPI_DISABLED=true.
n8n cloud vs self-hosted (API)
L’API non è disponibile nel free trial; su Cloud hai URL gestito; su self-hosted controlli tutte le superfici (incluso il playground).

Risorse ed endpoint chiave: Workflows, Executions, Credentials, Tags, Projects

Mappa concettuale delle risorse:

Workflows: definizioni, stato attivo/inattivo, tag, trasferimenti.
Executions: storico esecuzioni, stato/progresso, retry.
Credentials: creazione ed eliminazione; schema di credenziali accessibile via endpoint dedicato.
Tags e Projects: organizzazione e permessi.
Variables, SourceControl (Enterprise): interoperabilità con ambienti/versioning.

Autenticazione in tutti gli esempi: -H “X-N8N-API-KEY: YOURSECRETTOKEN”

Workflows: creare, leggere, attivare/disattivare
GET /workflows?active=true&limit=150

curl -X GET ‘https://your-instance.app.n8n.cloud/api/v1/workflows?active=true&limit=150’ \

-H ‘accept: application/json’ \

-H ‘X-N8N-API-KEY: YOURSECRETTOKEN’

POST /workflows (provisioning da JSON esportato)

curl -X POST ‘https://your-instance.app.n8n.cloud/api/v1/workflows’ \

-H ‘Content-Type: application/json’ \

-H ‘X-N8N-API-KEY: YOURSECRETTOKEN’ \

–data @workflow.json

Suggerimento: esporta un workflow di riferimento dall’editor e riutilizza quel JSON.

POST /workflows/{id}/activate e /deactivate

curl -X POST ‘https://your-instance.app.n8n.cloud/api/v1/workflows/{id}/activate’ \

-H ‘X-N8N-API-KEY: YOURSECRETTOKEN’

Executions: consultare, dettaglio, retry
GET /executions?limit=100
GET /executions/{id}

curl -X GET ‘https://your-instance.app.n8n.cloud/api/v1/executions/{id}’ \

-H ‘accept: application/json’ \

-H ‘X-N8N-API-KEY: YOURSECRETTOKEN’

POST /executions/{id}/retry per rieseguire una run fallita
Credentials: creare/eliminare e schema
GET /credentials/schema/{credentialTypeName}

curl -X GET ‘https://your-instance.app.n8n.cloud/api/v1/credentials/schema/openai’ \

-H ‘X-N8N-API-KEY: YOURSECRETTOKEN’

POST /credentials, DELETE /credentials/{id}
Tags, Projects, Variables: CRUD per organizzazione e governance.

Paginazione degli endpoint n8n: vedi la sezione dedicata per limit e cursor.

Codici di risposta ed errori in n8n: attesi 200/204 su successo; 401/403 per auth/permessi; 404 su risorsa inesistente. Implementa retry/backoff sul client quando opportuno.

Flusso end-to-end: provisioning via API, trigger via Webhook, lettura risultati

Obiettivo: creare/aggiornare un workflow via codice, avviarne l’esecuzione con un webhook e leggere i risultati.

Step 1 — Crea/aggiorna workflow via API

Esporta un workflow base dall’editor (con nodo Webhook + “Respond to Webhook”) e salvalo come workflow.json.
Provisioning:
POST /workflows con –data @workflow.json
Attivazione:
POST /workflows/{id}/activate

[IMG: Workflow con nodo “Webhook” che entra in “Respond to Webhook”]

Step 2 — Avvio esecuzioni di n8n via richiesta HTTP (webhook in n8n)

Nel nodo Webhook, definisci Path e metodo (es. POST).
Copia l’URL di produzione del Webhook.
Esegui:

curl -X POST ‘https:///webhook/‘ \

-H ‘Content-Type: application/json’ \

-d ‘{ “email”:”lead@example.com”,”campaign”:”winter” }’

Il nodo “Respond to Webhook” restituisce la risposta HTTP. Personalizza status e body.

[IMG: Pannello impostazioni del nodo “Webhook” con Path e Methods]

Step 3 — Recupera stato e dati esecuzione

Se il workflow registra un reference dell’executionId (ad es. in un log o in output), interroga:

curl -X GET ‘https://your-instance.app.n8n.cloud/api/v1/executions/{id}’ \

-H ‘accept: application/json’ \

-H ‘X-N8N-API-KEY: YOURSECRETTOKEN’

Integra nel tuo stack dati (DB/BI) o invia notifiche.

Bonus: chiamare l’API n8n da un workflow

Usa il nodo “HTTP Request” con header X-N8N-API-KEY per gestire workflow e esecuzioni in modo programmatico da n8n stesso (utile per strumenti interni).

[IMG: Config del nodo “HTTP Request” con URL API e header X-N8N-API-KEY]

Testing, paginazione, error handling e CI/CD

API playground n8n (self-hosted)

Percorso: ://api/v1/docs
Nota: usa dati reali e passa tramite proxy Scalar; valida solo in ambienti di test, non in produzione.
Autorizza via X-N8N-API-KEY dentro l’interfaccia.

Paginazione: pattern comuni, parametri tipici

Gli endpoint supportano limit e cursor.
Primo page fetch:

curl -X GET ‘/api/v1/workflows?active=true&limit=150′ \

-H ‘accept: application/json’ -H ‘X-N8N-API-KEY: …’

La risposta include nextCursor. Prossima pagina:

curl -X GET ‘/api/v1/workflows?active=true&limit=150&cursor=NEXT_CURSOR’ \

-H ‘accept: application/json’ -H ‘X-N8N-API-KEY: …’

Suggerimenti: usa batch asincroni e salva checkpoint del cursor per riprendere da errori in import massivi o audit/monitoraggio.

Error handling: codici di risposta, retry/backoff, idempotenza lato client

Prevedi 401/403/404, gestisci 5xx con exponential backoff.
Per operazioni di creazione, usa request-id/idempotency-key lato client quando possibile, o verifica a posteriori con GET per evitare duplicati.

Versionamento e promozione ambienti

Enterprise: Source control and environments per gestire Git, branch e promozione tra dev/stage/prod. Endpoint utile: POST /source-control/pull.
Strategie CI/CD:
Commit dei workflow JSON in repo privato.
Pipeline che: valida JSON, distribuisce via POST /workflows, attiva via /workflows/{id}/activate, applica tag e progetti.
Variabili e segreti esterni: collega le credenziali senza includerle nei JSON (gestione delle credenziali con n8n).
Monitoraggio dei log di esecuzione n8n:
GET /executions e GET /executions/{id} per lo stato.
In self-hosted, configura execution data e log streaming verso il tuo SIEM/observability stack.

[IMG: Diagramma CI/CD: repo → pipeline → API n8n (workflows/activations) → ambienti]

Quick Takeaways

L’API pubblica usa X-N8N-API-KEY: scegli scope minimi (Enterprise) e ruota le chiavi.
Scegli API pubblica per provisioning/governance, Webhook per avviare workflow, HTTP Request per integrare servizi esterni.
Paginazione nativa con limit e cursor: salva nextCursor e processa in batch.
Usa l’API playground n8n in ambienti di test: opera su dati reali.
Per CI/CD: versiona i workflow JSON, promuovi con /workflows e source control.
Monitora executions via /executions e configura log streaming in self-hosted.
Gestisci i segreti fuori dai JSON e separa dev/stage/prod.

Conclusione

Con l’api n8n porti la tua automazione da “click nell’editor” a “gestione via codice”: provisioning rapido di workflow, attivazione controllata, tagging coerente, retry delle esecuzioni e integrazione nei processi di rilascio. Per i marketer questo significa automazione avanzata davvero scalabile: orchestrare campagne, arricchire lead, consolidare report e lanciare task ripetitivi in secondi, con audit trail e governance. Ricorda i tre pilastri: 1) API pubblica per gestire le risorse e l’assetto dell’istanza, 2) webhook in n8n per avviare flussi “on demand” dai tuoi strumenti, 3) nodi “API” per dialogare con SaaS e data source esterni.

Inizia dal piccolo: crea una chiave, lista i workflow attivi, attiva/disattiva un flusso, prova la paginazione. Poi passa all’end-to-end: esporta un workflow con Webhook, caricalo via POST /workflows, attivalo, triggeralo da un CRM o da un modulo, leggi i risultati con GET /executions/{id}. Quando sei pronto per il salto, porta i JSON in Git e automatizza la promozione con pipeline CI/CD, separando ambienti e ruoli, e mettendo in sicurezza segreti e permessi. Pronto a raddoppiare la tua produttività? Sfrutta l’api n8n nelle tue routine quotidiane di marketing e libera tempo per ciò che conta: creatività, strategia e crescita.

Domande frequenti (FAQ)

Come funziona l’autenticazione bearer nelle API di n8n?
L’API pubblica di n8n usa API key via header X-N8N-API-KEY, non Authorization: Bearer. Le bearer token restano utili quando chiami API esterne dal nodo “HTTP Request”.
Posso avviare un workflow via endpoint per workflow su n8n?
Per avviare esecuzioni di n8n via richiesta HTTP, usa un Webhook in n8n nel workflow. L’API pubblica è ottima per provisioning e gestione; il trigger runtime avviene via URL del Webhook.
Come gestisco la paginazione degli endpoint n8n?
Usa limit e cursor. La risposta include nextCursor: passalo alla chiamata successiva per ottenere le pagine successive. Esempio: GET /workflows?limit=150&cursor=…
Come faccio il monitoraggio dei log di esecuzione n8n?
Consulta GET /executions e GET /executions/{id}. In self-hosted abilita le opzioni di “Execution data” e valuta il log streaming verso strumenti di osservabilità.
Qual è la differenza tra n8n cloud vs self-hosted (API)?
Su Cloud l’API è disponibile (non nel free trial) con base URL https://{instance}.app.n8n.cloud/api/v1. Self-hosted offre pieno controllo, inclusa la possibilità di usare l’API playground n8n su /api/v1/docs e di disabilitare l’API via env var.

Hai trovato utile questa guida? Dimmelo con un commento: qual è il primo flusso che automatizzerai con l’api n8n? Se ti è stato d’aiuto, condividila con un collega marketer che vuole risparmiare tempo e fare automazione “seria” con n8n!

L’API di n8n spiegata: come gestire i workflow via codice

API pubblica vs Webhook vs nodi “API”: differenze e quando usarli

Autenticazione, sicurezza e permessi: come proteggere l’API

Risorse ed endpoint chiave: Workflows, Executions, Credentials, Tags, Projects

Flusso end-to-end: provisioning via API, trigger via Webhook, lettura risultati

Testing, paginazione, error handling e CI/CD

Quick Takeaways

Conclusione

Domande frequenti (FAQ)

Articoli correlati

Partiamo da un processo che oggi vi costa ore

Raccontaci cosa vuoi automatizzare