Risolvere i problemi dei webhook n8n: guida completa per istanze sulla propria infrastruttura

Gestire n8n sulla propria infrastruttura offre grandi possibilità e risparmi, ma le integrazioni webhook possono talvolta fallire in modi che non si verificano nelle soluzioni ospitate nel cloud. Se vedi errori «Execution cancelled» o webhook che semplicemente non si attivano, non sei il solo. Vedremo come diagnosticare e risolvere i problemi più comuni dei webhook nelle installazioni n8n gestite sulla propria infrastruttura.

Il problema: quando i webhook smettono di rispondere

Hai configurato correttamente l’istanza n8n seguendo il nostro tutorial completo, tutto sembra perfetto, ma all’improvviso i bot Telegram smettono di rispondere, i webhook delle API scadono per timeout e le esecuzioni vengono annullate con messaggi di errore criptici. La causa tipica è una configurazione mancante ma essenziale, che n8n nel cloud gestisce automaticamente.

Che cosa risolverai

Al termine di questa guida avrai:

• ✅ URL dei webhook configurati correttamente per tutti i servizi esterni
• ✅ Integrazioni con i bot Telegram funzionanti con gestione affidabile dei messaggi
• ✅ Webhook API funzionanti dai servizi di terze parti
• ✅ Meno errori «execution cancelled» causati da configurazioni errate dei webhook
• ✅ Una configurazione dei webhook pronta per la produzione che rimane valida dopo i riavvii del server
• ✅ Competenze avanzate di diagnosi per futuri problemi dei webhook

Prerequisiti

• Installazione n8n funzionante, preferibilmente basata sulla nostra guida alla configurazione su Hetzner
• n8n in esecuzione dietro un reverse proxy, come Traefik o Nginx
• HTTPS abilitato con certificati SSL validi
• Accesso SSH al server
• Conoscenze di base di Docker e della riga di comando

Comprendere la causa di fondo

Perché i webhook di n8n sulla propria infrastruttura non funzionano

Quando esegui n8n dietro un reverse proxy, come è opportuno fare per sicurezza e SSL, n8n deve conoscere il proprio URL pubblico per generare endpoint webhook corretti. Senza questa configurazione, n8n crea URL come:

❌ Wrong: https://yourdomain.com:5678/webhook/abc123
❌ Wrong: http://localhost:5678/webhook/abc123

Anziché nel formato corretto:

✅ Correct: https://yourdomain.com/webhook/abc123

La variabile d’ambiente mancante

La soluzione è la variabile d’ambiente WEBHOOK_URL, che indica a n8n esattamente dove è accessibile pubblicamente. Nelle soluzioni cloud viene impostata automaticamente, mentre nelle installazioni sulla propria infrastruttura va configurata manualmente. A ottobre 2026, n8n 2.35.0 e versioni successive la documentano come N8N_WEBHOOK_URL; WEBHOOK_URL funziona ancora come alias deprecato che genera un avviso nei log all’avvio.

Passo 1: diagnosticare la configurazione attuale

Controlla la configurazione del container

Per prima cosa, controlla la configurazione attuale di n8n:

# Navigate to your n8n directory
cd /opt/n8n

# Check current environment variables
cat docker-compose.yml | grep -A 20 "environment:"

Verifica la generazione degli URL dei webhook

Crea un semplice flusso di lavoro con un webhook per vedere quali URL genera n8n:

1. Apri l’interfaccia di n8n
2. Crea un nuovo flusso di lavoro
3. Aggiungi un nodo di attivazione «Webhook»
4. Prendi nota dell’URL generato

Se l’URL include :5678 o usa localhost, hai il problema che stiamo risolvendo.

Controlla i log del container

Cerca errori relativi ai webhook:

# Check n8n logs for webhook issues
docker logs n8n-n8n-1 | grep -i webhook

# Look for execution errors
docker logs n8n-n8n-1 | grep -i "cancelled\|timeout\|failed"

Passo 2: risolvere il problema principale — aggiungere WEBHOOK_URL

Per una singola istanza n8n

Se hai seguito la nostra guida originale alla configurazione, modifica il file Docker Compose:

cd /opt/n8n
# Create backup first
cp docker-compose.yml docker-compose.yml.backup

# Edit the configuration
nano docker-compose.yml

Aggiungi la variabile d’ambiente WEBHOOK_URL alla configurazione esistente. L’esempio imposta anche N8N_PROXY_HOPS=1, che la guida di n8n al reverse proxy raccomanda dietro un singolo proxy come Traefik:

version: '3'

services:
  n8n:
    image: n8nio/n8n:1.95.2
    restart: always
    environment:
      - N8N_HOST=n8n.yourdomain.com
      - NODE_ENV=production
      - N8N_PROTOCOL=https
      - N8N_PORT=5678
      - N8N_EDITOR_BASE_URL=https://n8n.yourdomain.com
      - N8N_EMAIL_MODE=smtp
      - N8N_SMTP_HOST=mailserver
      - N8N_SMTP_PORT=25
      - N8N_SMTP_SSL=false
      - N8N_SMTP_USER=
      - N8N_SMTP_PASS=
      - [email protected]
      - N8N_PROXY_HOPS=1
      - N8N_RUNNERS_ENABLED=true
      # 🔧 ADD THIS LINE - Critical for webhook functionality
      - WEBHOOK_URL=https://n8n.yourdomain.com
    volumes:
      - ./data:/home/node/.n8n
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.n8n.rule=Host(`n8n.yourdomain.com`)"
      - "traefik.http.routers.n8n.entrypoints=https"
      - "traefik.http.routers.n8n.tls.certresolver=letsencrypt"
      - "traefik.http.services.n8n.loadbalancer.server.port=5678"

networks:
  proxy:
    external: true

Per più istanze n8n

Se esegui più istanze n8n, ad esempio per team diversi, ciascuna deve avere il proprio WEBHOOK_URL:

# First instance (/opt/n8n/docker-compose.yml)
environment:
  - WEBHOOK_URL=https://n8n.yourdomain.com

# Second instance (/opt/n8n-team2/docker-compose.yml)  
environment:
  - WEBHOOK_URL=https://team2.yourdomain.com

Riavvia il container

Applica le modifiche:

# Stop the container
docker compose down

# Start with new configuration
docker compose up -d

# Verify it's running
docker ps | grep n8n

Passo 3: verificare la correzione

Controlla i log del container

Il log di avvio mostra l’URL dell’editor. Conferma che n8n conosce il proprio indirizzo pubblico, ma non che i webhook siano registrati: verifica quindi anche l’URL in un nodo Webhook (passaggio successivo):

docker logs n8n-n8n-1 --tail 10

Cerca questa riga:

Editor is now accessible via:
https://n8n.yourdomain.com  # ✅ Should NOT include :5678

Verifica la generazione dei webhook

1. Torna al flusso di lavoro del webhook di prova
2. Elimina il vecchio nodo webhook
3. Aggiungi un nuovo nodo webhook
4. Verifica che l’URL generato sia corretto: https://yourdomain.com/webhook/..., senza numero di porta

Verifica un webhook esterno

Crea un semplice flusso di prova con un nodo Webhook impostato su POST e con il percorso test, poi attivalo (pubblicalo) per registrarne l’URL di produzione e richiamalo:

# Test with curl
curl -X POST https://n8n.yourdomain.com/webhook/test \
  -H "Content-Type: application/json" \
  -d '{"test": "webhook working"}'

Passo 4: configurare l’integrazione con un bot Telegram

La particolarità di Telegram

Telegram richiede webhook HTTPS e impone requisiti rigorosi per gli URL. Ecco come configurare un bot Telegram funzionante:

Crea il flusso di lavoro del bot Telegram

1. Crea un nuovo flusso di lavoro in n8n
2. Aggiungi un nodo «Telegram Trigger»
3. Configura il token del bot
4. L’URL del webhook dovrebbe ora avere il formato corretto

Registra il webhook su Telegram

# Replace YOUR_BOT_TOKEN with your actual token
# Replace the webhook URL with your actual webhook URL from n8n

curl -F "url=https://n8n.yourdomain.com/webhook/abc123" \
https://api.telegram.org/botYOUR_BOT_TOKEN/setWebhook

Verifica il webhook Telegram

Controlla se Telegram riesce a raggiungere il webhook:

curl https://api.telegram.org/botYOUR_BOT_TOKEN/getWebhookInfo

Dovresti vedere:

{
  "ok": true,
  "result": {
    "url": "https://n8n.yourdomain.com/webhook/abc123",
    "has_custom_certificate": false,
    "pending_update_count": 0
  }
}

Passo 5: configurazione avanzata dei webhook

Abilita il supporto WebSocket in Traefik

Le normali richieste webhook usano HTTP e non richiedono il supporto WebSocket. La connessione push dell’editor di n8n usa WebSocket, supportato nativamente da Traefik, quindi le etichette standard sono normalmente sufficienti. Non aggiungere un middleware che forzi gli header Connection: Upgrade su ogni richiesta: a Traefik bastano queste etichette:

# Standard labels in your n8n docker-compose.yml (no extra middleware needed)
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.n8n.rule=Host(`n8n.yourdomain.com`)"
  - "traefik.http.routers.n8n.entrypoints=https"
  - "traefik.http.routers.n8n.tls.certresolver=letsencrypt"
  - "traefik.http.services.n8n.loadbalancer.server.port=5678"

Configura le impostazioni di payload e dati di esecuzione

Queste impostazioni non modificano i timeout: memorizzano i dati binari su disco, impostano la dimensione massima del payload e conservano i dati di esecuzione per il debug. N8N_PAYLOAD_SIZE_MAX accetta un numero in MiB (16 per impostazione predefinita), quindi scrivi 16 invece di 16MB. Per i timeout di esecuzione, consulta EXECUTIONS_TIMEOUT nella sezione sulla gestione delle code dei webhook più avanti:

environment:
  # Add these for webhook reliability
  - N8N_DEFAULT_BINARY_DATA_MODE=filesystem
  - N8N_PAYLOAD_SIZE_MAX=16
  - EXECUTIONS_DATA_SAVE_ON_ERROR=all
  - EXECUTIONS_DATA_SAVE_ON_SUCCESS=all
  - EXECUTIONS_DATA_SAVE_MANUAL_EXECUTIONS=true

Risoluzione dei problemi comuni

Problema: gli URL contengono ancora numeri di porta

Sintomi:

• Gli URL dei webhook mostrano ancora :5678
• I servizi esterni non riescono a raggiungere i webhook

Soluzione:

# Check if environment variable is properly set
docker exec n8n-n8n-1 env | grep WEBHOOK_URL

# If missing, recreate container:
docker compose down
docker compose up -d --force-recreate

Problema: «Bad webhook: HTTPS URL must be provided»

Sintomi:

• La configurazione del bot Telegram non riesce
• L’errore indica che è richiesto HTTPS

Causa: L’URL del webhook non usa HTTPS oppure ci sono problemi con il certificato SSL.

Soluzione:

# Test SSL certificate
curl -I https://n8n.yourdomain.com

# Check Traefik logs for SSL issues
docker logs traefik | grep -i certificate

# Verify domain DNS points to your server
nslookup n8n.yourdomain.com

Problema: i webhook funzionano in modalità di test ma non in produzione

Sintomi:

• Le esecuzioni dei webhook di prova funzionano correttamente
• I webhook di produzione scadono per timeout o non funzionano

Soluzione:

# Check for webhook URL conflicts
docker logs n8n-n8n-1 | grep "webhook.*test"

# Ensure production workflows use production URLs
# Deactivate test workflows before activating production ones

Problema: «Connection reset by peer» o 502 Bad Gateway

Sintomi:

• Errori intermittenti dei webhook
• Errori del gateway nei log

Soluzione:

# Check if container is running out of memory
docker stats n8n-n8n-1

# Increase container resources if needed:
# Add to docker-compose.yml under the n8n service:
deploy:
  resources:
    limits:
      memory: 2G
    reservations:
      memory: 1G

Considerazioni sulla sicurezza

Elenco degli IP autorizzati per i webhook

Per i webhook sensibili, valuta restrizioni sugli indirizzi IP:

# In your webhook node configuration
"ipWhitelist": ["192.168.1.0/24", "10.0.0.0/8"]

Autenticazione dei webhook

Usa sempre l’autenticazione dei webhook quando possibile:

# In your webhook configuration
"authenticationMethod": "headerAuth"
"authenticationData": {
  "name": "X-API-Key",
  "value": "your-secret-key"
}

Limiti di frequenza delle richieste

Proteggi i webhook dagli abusi. Un router accetta una sola etichetta middlewares e una seconda etichetta con la stessa chiave sostituisce la prima; se il router usa già altri middleware, elencali tutti in un’unica etichetta separati da virgole:

# Add to Traefik labels
- "traefik.http.middlewares.rate-limit.ratelimit.average=10"
- "traefik.http.middlewares.rate-limit.ratelimit.burst=20"
- "traefik.http.routers.n8n.middlewares=rate-limit"

Monitoraggio e manutenzione

Monitora lo stato dei webhook

Crea un flusso di monitoraggio:

1. Aggiungi un nodo di attivazione «Cron», ogni 5 minuti
2. Aggiungi un nodo «HTTP Request» per verificare il webhook
3. Aggiungi una logica di notifica in caso di errore

Registra l’attività dei webhook

Abilita la registrazione dettagliata dei webhook:

environment:
  - N8N_LOG_LEVEL=debug
  - N8N_LOG_OUTPUT=console,file
  - N8N_LOG_FILE_COUNT_MAX=100
  - N8N_LOG_FILE_SIZE_MAX=16

Esegui il backup delle configurazioni dei webhook

Lo script esporta con --all tutti i flussi e tutte le credenziali, ciascuno in un unico file. Le credenziali esportate restano crittografate: conserva quindi la chiave di crittografia dell’istanza insieme ai backup.

#!/bin/bash
# Create webhook backup script
mkdir -p /opt/backups/webhook-configs
cd /opt/n8n

# Backup workflow definitions
docker exec n8n-n8n-1 n8n export:workflow --all --output=/tmp/workflows-backup.json
docker cp n8n-n8n-1:/tmp/workflows-backup.json /opt/backups/webhook-configs/workflows-$(date +%Y%m%d).json

# Backup credentials
docker exec n8n-n8n-1 n8n export:credentials --all --output=/tmp/credentials-backup.json  
docker cp n8n-n8n-1:/tmp/credentials-backup.json /opt/backups/webhook-configs/credentials-$(date +%Y%m%d).json

Ottimizzazione delle prestazioni

Ottimizzazione delle risposte dei webhook

Configura risposte efficienti per i webhook. Alcune guide meno recenti impostano anche N8N_BINARY_DATA_TTL e N8N_PERSISTED_BINARY_DATA_TTL; n8n non le usa più e chiede di rimuoverle:

environment:
  # Optimize for webhook performance
  - N8N_DISABLE_UI=false
  - GENERIC_TIMEZONE=UTC

Pulizia del database per i webhook

I webhook con volumi elevati possono riempire il database. n8n elimina automaticamente i vecchi dati di esecuzione (EXECUTIONS_DATA_PRUNE=true, conservando fino a 336 ore e 10.000 esecuzioni); riduci EXECUTIONS_DATA_MAX_AGE (ore) e EXECUTIONS_DATA_PRUNE_MAX_COUNT per conservarne meno. La CLI di n8n non ha un comando di pulizia delle esecuzioni, quindi imposta i limiti nell’ambiente del servizio n8n invece che in un cron job, per esempio 30 giorni e al massimo 1.000 esecuzioni:

environment:
  # Prune executions older than 30 days (720 hours), keep at most 1,000
  - EXECUTIONS_DATA_PRUNE=true
  - EXECUTIONS_DATA_MAX_AGE=720
  - EXECUTIONS_DATA_PRUNE_MAX_COUNT=1000

Test delle integrazioni webhook

Suite di test per i tipi di webhook comuni

Crea flussi di prova per diversi tipi di webhook:

Webhook REST API semplice:

{
  "method": "POST",
  "url": "https://n8n.yourdomain.com/webhook/test-api",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "test": true,
    "timestamp": "{{new Date().toISOString()}}"
  }
}

Test del bot Telegram: Invia un messaggio al bot e verifica che il flusso di lavoro si attivi correttamente.

Test di invio di un modulo:

<form action="https://n8n.yourdomain.com/webhook/form-test" method="POST">
  <input type="text" name="name" value="Test User">
  <input type="email" name="email" value="[email protected]">
  <button type="submit">Test Webhook</button>
</form>

Scalare l’infrastruttura dei webhook

Più istanze n8n con bilanciamento del carico

Per elaborare volumi elevati di webhook, esegui processori webhook dedicati (n8n webhook) in modalità coda. Richiedono lo stesso database PostgreSQL, Redis e la stessa chiave di crittografia dell’istanza principale e dei worker. Traefik aggiunge un server per ogni container di un servizio, quindi le due repliche condividono un’unica etichetta di porta e la regola più lunga invia le richieste /webhook/ ai processori, mentre l’editor resta sull’istanza principale:

# docker-compose.yml sketch: two webhook processors in queue mode
# (main instance, workers, PostgreSQL and Redis configured as in the queue section below)
services:
  n8n-webhook:
    image: n8nio/n8n:1.95.2
    command: webhook
    restart: always
    deploy:
      replicas: 2
    environment:
      - EXECUTIONS_MODE=queue
      - WEBHOOK_URL=https://n8n.yourdomain.com
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      # ... same database and Redis settings as the main instance
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.n8n-webhook.rule=Host(`n8n.yourdomain.com`) && PathPrefix(`/webhook/`)"
      - "traefik.http.routers.n8n-webhook.entrypoints=https"
      - "traefik.http.routers.n8n-webhook.tls.certresolver=letsencrypt"
      - "traefik.http.services.n8n-webhook.loadbalancer.server.port=5678"

networks:
  proxy:
    external: true

Gestione delle code dei webhook

Per gestire picchi di webhook, la modalità coda richiede anche PostgreSQL (SQLite non è supportato), processi worker separati e la stessa chiave di crittografia sull’istanza principale e su tutti i worker. EXECUTIONS_TIMEOUT e EXECUTIONS_TIMEOUT_MAX sono espressi in secondi:

environment:
  - QUEUE_BULL_REDIS_HOST=redis
  - QUEUE_BULL_REDIS_PORT=6379
  - EXECUTIONS_MODE=queue
  - EXECUTIONS_TIMEOUT=3600
  - EXECUTIONS_TIMEOUT_MAX=7200

Impatto su costi e prestazioni

Costi di elaborazione dei webhook

Se configurata correttamente, l’elaborazione dei webhook è estremamente efficiente:

• Risorse del server: impatto minimo su CPU e memoria per la maggior parte dei webhook
• Archiviazione: i dati delle esecuzioni aumentano con il volume dei webhook
• Rete: la larghezza di banda necessaria aumenta con le dimensioni dei payload

Confronto dei costi

Elaborazione dei webhook sulla propria infrastruttura rispetto alle alternative cloud:

• n8n Cloud Starter: €20/mese con fatturazione annuale (2.500 esecuzioni, a ottobre 2026)
• Sulla propria infrastruttura (Hetzner CX23): €5,99/mese IVA esclusa, incluso un indirizzo IPv4 primario, a ottobre 2026 (nessun costo per esecuzione; capacità limitata dalle risorse del server)
• Risparmio: circa €168 all’anno, senza quote di esecuzione

Esempi avanzati di integrazione

Pipeline dai webhook al database

Esempio completo di integrazione tra webhook e database:

# Workflow: API Webhook → Data Validation → Database Insert
# 1. Webhook Trigger (receives data)
# 2. Function Node (validates/transforms data)  
# 3. Database Node (inserts processed data)
# 4. HTTP Response (confirms receipt)

Router webhook per più servizi

Instrada i diversi tipi di webhook ai gestori appropriati:

# Workflow: Webhook Router
# 1. Webhook Trigger (catches all webhooks)
# 2. Switch Node (routes by webhook source)
# 3. Multiple branches for different services
# 4. Appropriate response formatting

Conclusione

Webhook configurati correttamente sono essenziali per un’installazione n8n pronta per la produzione. La variabile d’ambiente WEBHOOK_URL è l’impostazione più importante per l’affidabilità dei webhook nelle installazioni sulla propria infrastruttura. Con una corretta configurazione SSL e il monitoraggio, la tua istanza n8n può gestire carichi di lavoro webhook che altrimenti richiederebbero un piano cloud di fascia superiore.

Vantaggi principali di questa configurazione

• Conveniente: nessun costo per esecuzione su un server da circa €6/mese (a ottobre 2026)
• Affidabile: la configurazione testata in produzione gestisce scenari con volumi elevati
• Sicura: HTTPS, autenticazione e limiti di frequenza delle richieste proteggono l’infrastruttura
• Scalabile: l’architettura supporta la crescita dai progetti personali ai flussi di lavoro aziendali
• Riservata: i payload dei webhook vengono elaborati sul tuo server; i dati escono solo quando i tuoi flussi li inviano a servizi esterni come Telegram

Questa guida completa il nostro tutorial originale sulla configurazione di n8n per creare una piattaforma di automazione completa e pronta per i webhook. Che tu elabori messaggi Telegram, callback API o invii di moduli, la tua istanza n8n ora li gestisce tutti in modo affidabile e conveniente.

Per scenari webhook complessi o implementazioni di livello aziendale, valuta una consulenza professionale per ottimizzare il tuo caso d’uso specifico.

---

Chi è tva

tva assicura una gestione completa dell’infrastruttura di sistemi di database, ambienti cloud e supply chain globali. Il nostro approccio metodico combina rigorosi protocolli di sicurezza con l’ottimizzazione delle prestazioni, mentre i servizi di consulenza strategica consentono un coordinamento preciso delle risorse digitali e fisiche, mantenendo i più alti standard di eccellenza operativa e conformità in tutti gli incarichi.

Visita tva.sg per maggiori informazioni sui nostri servizi e altri tutorial sull’automazione.