Creare API Personalizzate con il Nodo Webhook

Vuoi trasformare n8n in un gateway di servizi e integrazioni senza scrivere un server da zero? Con il nodo webhook n8n api personalizzate puoi pubblicare endpoint REST in pochi minuti: ricevere JSON o file, validare richieste in ingresso, orchestrare logica con altri nodi (DB, CRM, Slack) e rispondere con status code e payload controllati. In questa guida progettiamo un endpoint REST con n8n, impostiamo il nodo Webhook come trigger API, definiamo path, route params e query string, gestiamo autenticazione con header personalizzati, CORS e preflight, e vediamo come rispondere via Respond To Webhook. Troverai esempi pronti, snippet di configurazione esatti e best practice di sicurezza (verifica firma HMAC dei webhook, JWT Bearer per richieste in ingresso, IP allowlist e sicurezza in n8n), oltre a consigli per reverse proxy NGINX e tunnel per sviluppo locale (ngrok/Cloudflare). Obiettivo: creare API robuste, osservabili e facili da mantenere, perfette per marketer che vogliono automatizzare processi e collegare tool con flessibilità.

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

[IMG: Canvas con Webhook → Validazioni → Business Logic → Respond To Webhook → Log]

Il Webhook come “porta d’ingresso”: quando e perché usarlo

Il Webhook è il trigger ideale quando vuoi esporre un endpoint REST con n8n che riceve eventi o invocazioni sincrone da altri sistemi. Immagina casi come: form che inviano lead, bot/integrazioni che notificano eventi, servizi esterni che richiedono un’azione (es. generare un documento, verificare un dato, avviare un workflow). Con il nodo Webhook come trigger API crei rapidamente un URL pubblico, instradi i dati nel flusso e decidi come rispondere.

Perché funziona bene per API personalizzate

Tempo di setup minimo: configuri path e methods e sei online.
Integrazione rapida: puoi combinare HTTP Request, DB, CRM e tool di messaging senza codice server.
Controllo della risposta: scegli se rispondere subito o dopo l’elaborazione, con status code e JSON a tua scelta.

Pattern tipici

Ingestion dati con JSON e content-type application/json, con convalida di campi e formati.
Router condizionali in base a route params e query string (es. /api/users/:id?action=deactivate).
Ricezione di notifiche esterne firmate (HMAC) e gestione idempotente.
Servizi “utility” (enrichment, normalizzazione) dietro un endpoint con JWT Bearer per richieste in ingresso.

Per i marketer, questo significa trasformare fogli, CRM e tool martech in un’orchestrazione a micro-servizi, dove ogni pezzo può essere chiamato da campagne, strumenti di BI o app interne.

Progettare l’endpoint: path, methods e accesso ai dati

Per costruire un endpoint REST con n8n, imposta nel nodo Webhook i parametri chiave.

Parametri del nodo Webhook (esatti)

path: definisce il segmento di URL (es. “incoming-data”).
methods: array dei metodi ammessi (ad esempio [“POST”]).
responseMode: modalità di risposta (“onReceived” oppure “lastNode”).
responseData: struttura per risposta immediata quando usi onReceived.

Esempio di configurazione (estratto concettuale)

{
  "type": "n8n-nodes-base.webhook",
  "parameters": {
    "path": "incoming-data",
    "methods": ["POST"],
    "responseMode": "onReceived",
    "responseData": {
      "statusCode": 200,
      "body": "Webhook received successfully"
    }
  }
}

Accesso ai dati in flusso

Body JSON: accedi ai campi con espressioni in nodi successivi, ad esempio {{ $json[“body”][“email”] }}.
Query string: disponibile nello stesso payload (es. {{ $json[“query”][“utm_source”] }}).
Headers: leggibili per validazioni (token, firma).

Route params e query string

Disegna i tuoi path con placeholder logici (es. /orders/:id), quindi usa un nodo Code o IF per estrarre/validare i segmenti dall’URL completo se necessario. Le query sono direttamente disponibili in $json.query.

Suggerimento

Mappa e valida il payload in un nodo Code iniziale: controlla required fields, tipi e range; se non valido, prepara un esito 400 che invierai con Respond To Webhook.

[IMG: Nodo Webhook con path “incoming-data”, methods POST e responseMode=onReceived]

Modalità di risposta: sincrona vs asincrona e il nodo “Respond To Webhook”

Decidi quando e come rispondere al chiamante:

responseMode nel Webhook

“onReceived”: rispondi subito all’arrivo della richiesta (adatto a webhook che non richiedono attesa).
“lastNode”: il Webhook attende la fine del flusso e restituisce l’output dell’ultimo nodo.

Risposte personalizzate con Respond To Webhook

Usa il nodo “Respond To Webhook” per inviare status code, headers e body controllati.

Parametri del nodo Respond To Webhook (esatti)

responseMode: “responseNode”
options.responseData: oggetto con body, headers e statusCode

Esempio: risposta JSON 201 con header

{
  "type": "n8n-nodes-base.respondToWebhook",
  "parameters": {
    "responseMode": "responseNode",
    "options": {
      "responseData": {
        "statusCode": 201,
        "headers": { "Content-Type": "application/json" },
        "body": "{\"status\":\"created\",\"id\":\"={{ $json.id }}\"}"
      }
    }
  }
}

Linee guida pratiche

Se devi orchestrare logiche costose (es. chiamate a terze parti), preferisci “lastNode” o rispondi subito con 202 e fornisci un “tracking id” (poi notifica via webhook/Slack/Email al termine).
Stratifica i casi d’errore con status code adeguati (400, 401, 403, 404, 409, 422, 429, 500) e messaggi coerenti per il client.

[IMG: Webhook → Validazioni → Business Logic → Respond To Webhook (201/422)]

Sicurezza applicativa: header auth, HMAC, JWT, CORS e IP allowlist

Autenticazione con header personalizzati

Pretendi un header di autenticazione (es. x-api-key) e rifiuta richieste senza chiave valida (401/403).
In un nodo Code iniziale, confronta la chiave con un valore sicuro in variabili d’ambiente.

Verifica firma HMAC dei webhook

Per provider (es. Stripe, shop, ESP) che inviano firma, ricalcola HMAC del body con il segreto condiviso e confronta con l’header (costante-time compare). Se non coincide, 401.

Esempio (Code) — verifica firma HMAC del body

const crypto = require('crypto');
const signature = $json.headers['x-signature'] || '';
const secret = $env.WEBHOOK_SECRET;
const bodyRaw = JSON.stringify($json.body || {});
const expected = crypto.createHmac('sha256', secret).update(bodyRaw).digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
  return [{ json: { error: 'invalid_signature', statusCode: 401 }, continue: false }];
}
return [{ json: { verified: true, ...$json } }];

JWT Bearer per richieste in ingresso

Accetta Authorization: Bearer . In un nodo Code decodifica/verifica lo JWT (es. HS256 con secret). Se scaduto o non valido → 401.

CORS e preflight OPTIONS

Per UI/browser, includi Access-Control-Allow-Origin e Access-Control-Allow-Headers nella risposta. Gestisci il preflight con una risposta immediata (200) che riporta gli header CORS attesi.

IP allowlist e sicurezza in n8n

Limita l’esposizione dell’endpoint dietro un reverse proxy e consenti soltanto IP/ASN attesi se possibile. Mantieni segreti e chiavi in credenziali/variabili d’ambiente.

[IMG: Nodo Code “Auth Checks” prima della logica; ramo errore → Respond To Webhook 401]

File upload e binary: gestire multipart/form-data

Quando l’endpoint deve ricevere file (immagini, CSV), progetta il flusso per gestire multipart/form-data:

Accetta le richieste e instrada i campi del form e i binari come item del workflow.
Applica controlli su tipo e dimensione (es. MIME, peso massimo).
Salva i file su storage (S3/Drive) e restituisci metadati (URL, checksum).

Consigli pratici

Separa validazione dei metadati (nome, tipo) dall’upload fisico.
Esegui antivirus dove richiesto dalle policy.
Per grandi file, valuta pattern asincroni: rispondi 202 e invia notifica a fine processo.

[IMG: Webhook (multipart) → Validazioni → Upload S3 → Respond To Webhook (201 con JSON di esito)]

Deployment: URL, reverse proxy e tunnel per sviluppo

URL e ambienti

Usa ambienti separati (dev/stage/prod). In locale, sfrutta tunnel per sviluppo locale (ngrok/Cloudflare) per testare provider esterni che richiedono callback.
Versiona i path (es. /v1/…) per introdurre breaking change senza impatti ai client.

reverse proxy NGINX per n8n

Termina TLS/HTTPS, applica rate limit e dimensione massima richieste.
Reindirizza path /webhook/… verso l’istanza n8n; applica header di sicurezza (X-Content-Type-Options, X-Frame-Options, ecc.).

Capacity e affidabilità

Gestisci concurrency e timeout lato proxy; se l’elaborazione è lunga, preferisci risposte immediate e processi asincroni.
Monitora 4xx/5xx per individuare rapidamente problemi di client o regressioni del flusso.

[IMG: Diagramma NGINX ↔ n8n (Reverse Proxy, TLS, Rate Limit)]

Osservabilità, error handling e contratti d’API

Contratto d’API chiaro

Documenta schema di request/response, status code e esempi.
Mantieni compatibilità: aggiungere campi è OK, rimuoverli o cambiarli richiede una nuova versione dell’endpoint.

Error handling

Con Respond To Webhook, invia status code e messaggi coerenti.
Logga errori con dettagli minimi (no PII sensibile), includi correlation id per debug.

Metriche e logging

Registra count richieste, p95 latenza, tasso di 4xx/5xx, top errori e consumer principali.
Salva un audit trail (input minimizzato, esiti, tempi) per revisioni e compliance.

[IMG: Nodo “Log” verso DB/Sheets + dashboard con p95 latenza e errori]

Esempio end‑to‑end: endpoint POST /incoming-data con auth e risposta JSON

Obiettivo: ricevere un payload JSON con un lead, validare auth, processare e rispondere 201 con un id.

Webhook (trigger)

{
  "type": "n8n-nodes-base.webhook",
  "parameters": {
    "path": "incoming-data",
    "methods": ["POST"],
    "responseMode": "lastNode"
  }
}

Code: validazione auth + payload

// Header x-api-key richiesto e campi minimi: email
const key = $json.headers['x-api-key'];
if (key !== $env.INTAKE_KEY) {
  return [{ json: { error: 'unauthorized' , statusCode: 401 }, continue: false }];
}
const email = $json.body?.email;
if (!email || !/.+@.+\..+/.test(email)) {
  return [{ json: { error: 'invalid_email', statusCode: 422 }, continue: false }];
}
return [{ json: { ok: true, email } }];

Business logic (es. arricchimento, CRM)

Esegui Set/HTTP Request verso CRM.
Genera un id lead (es. in un nodo Code o come risposta del CRM).

Respond To Webhook: esito 201

{
  "type": "n8n-nodes-base.respondToWebhook",
  "parameters": {
    "responseMode": "responseNode",
    "options": {
      "responseData": {
        "statusCode": 201,
        "headers": { "Content-Type": "application/json" },
        "body": "{\"status\":\"created\",\"leadId\":\"={{ $json.leadId || 'temp-123' }}\"}"
      }
    }
  }
}

Estensioni

Aggiungi CORS in headers se ti serve in frontend.
Per health check, crea un secondo Webhook con path /health e risposta onReceived 200.

[IMG: Canvas: Webhook(POST) → Code(validazione) → HTTP(CRM) → Respond To Webhook(201)]

Quick Takeaways

Il nodo Webhook è l’ingresso per costruire endpoint REST con n8n; configura path, methods e responseMode.
Usa “onReceived” per risposte immediate e “lastNode” per attendere la logica di workflow; personalizza la risposta con Respond To Webhook.
Valida sempre input e autenticazione (header, HMAC, JWT) e gestisci CORS quando serve.
Per upload file, separa validazione da salvataggio e preferisci processi asincroni per payload grandi.
Metti l’endpoint dietro un reverse proxy NGINX, con TLS, rate limit e log; in sviluppo usa tunnel (ngrok/Cloudflare).
Definisci contratti stabili (schema, status code), versiona gli endpoint e monitora latenza/errori.

Conclusione

Creare servizi veloci e affidabili non richiede più un backend su misura: con il nodo webhook n8n api personalizzate pubblichi endpoint REST in pochi minuti, orchestrando tutto il necessario con i nodi della piattaforma. Dalla validazione del payload alla sicurezza (header token, HMAC, JWT), fino a CORS, upload file e risposta standardizzata, hai il pieno controllo del ciclo di vita della richiesta. Aggiungendo Respond To Webhook definisci status code e body precisi, mentre proxy e tunnel aiutano a testare e mettere in produzione in modo sicuro. Il consiglio pratico: parti da un endpoint singolo (intake lead o evento marketing), definisci contratto e metriche, poi estendi a una piccola suite di API per i tuoi processi chiave. In breve, trasformi n8n nella tua “colla” applicativa, riducendo tempi di integrazione e aumentando la produttività del team marketing.

FAQ

Come posso definire un endpoint REST con n8n?

Crea un workflow con il nodo Webhook come trigger API, imposta path e methods e instrada il payload verso la logica di business. Con Respond To Webhook restituisci status code e JSON personalizzati.

Posso controllare la risposta HTTP?

Sì. Imposta responseMode del Webhook a “lastNode” e usa Respond To Webhook per rispondere con status code, headers e body. In alternativa, con “onReceived” invii una risposta immediata predefinita.

Come gestisco autenticazione e sicurezza?

Valida header (x-api-key), verifica firma HMAC del body per webhook firmati o usa JWT Bearer per richieste in ingresso. Limita l’accesso con reverse proxy, CORS controllato e, se possibile, IP allowlist.

E per l’upload di file?

Accetta multipart/form-data, separa validazione e upload verso storage e ritorna metadati (URL, checksum) al client. Per file grandi, rispondi subito (202) e notifica l’esito a elaborazione completata.

Come lavoro in locale e poi metto in produzione?

Usa tunnel per sviluppo locale (ngrok/Cloudflare) per testare callback esterne. In produzione, metti n8n dietro un reverse proxy NGINX con TLS, rate limit e log. Versiona i path (es. /v1/) per gestire evoluzioni dell’API.

Ci dai una mano?

Qual è il primo endpoint che costruirai con n8n: intake lead, validazione ordini o utility di arricchimento? Condividi la tua idea con il team e diffondi questo articolo: confrontiamo pattern e best practice per API più veloci e sicure!