AI Automation Italia

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

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:
1) In n8n vai su Settings > n8n API > Create an API key.
2) Imposta Label, Expiration e (Enterprise) Scopes.
3) 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!

Articoli correlati

Vuoi automazioni AI su misura per la tua azienda?
Scopri la consulenza →
, , , , , , ,