How to Fix "Webhook URL shows Localhost" Error in n8n

The dreaded localhost webhook URL — and exactly how to replace it with your real domain in under 10 minutes.

🐞 You deployed n8n on a VPS, opened the Webhook node, and saw this: http://localhost:5678/webhook/your-path. You try to paste that URL into Shopify or Typeform and nothing works — of course it doesn't, localhost is your server talking to itself. The outside world has no idea where to find it.

I hit this exact wall the first time I deployed n8n on an Oracle Cloud free-tier instance. Spent two hours reading forum threads before I understood what was actually happening. This guide gives you everything I wish existed back then — the root cause, all four environment variable options, the Nginx proxy config that trips everyone up, and a full troubleshooting table for when the obvious fix doesn't work.

Why Does This Happen? The Real Explanation

Most guides jump straight to "set this variable and restart." That works, until it does not — and when it does not, you have no idea why. So let's spend two minutes understanding the actual mechanism.

How n8n Builds Webhook URLs

Every time you open a Webhook node in n8n, the editor generates a URL for you. It constructs that URL at runtime using environment variables in this priority order:

1. WEBHOOK_URL — if this is set, it is used as the complete base URL and everything else is ignored.
2. N8N_PROTOCOL + N8N_HOST + N8N_PORT — if WEBHOOK_URL is absent, n8n assembles the URL from these three pieces.
3. Fallback: http://localhost:5678 — if none of the above are set, this is what you get.

When you run n8n locally for development, the fallback is fine — your browser and your n8n instance are on the same machine. The moment you move to a VPS, your n8n instance is no longer "localhost" to the outside world. But n8n does not know your domain unless you tell it explicitly.

Setting WEBHOOK_URL is not optional on a self-hosted production instance. It is a required configuration step that the official n8n documentation lists but many deployment tutorials skip entirely. — Confirmed from n8n's official environment variables reference: docs.n8n.io/hosting/configuration/environment-variables

Why Nginx Makes It Worse Without Proper Headers

Many VPS setups run n8n behind an Nginx reverse proxy. This introduces a second layer of confusion: even after you set WEBHOOK_URL correctly, your Nginx config may be stripping or not forwarding the headers that tell n8n it is operating over HTTPS from a public domain.

If Nginx does not pass X-Forwarded-Proto: https, n8n may still generate http:// URLs internally even when your browser sees HTTPS. This is the "I set the variable but it still shows localhost or HTTP" variant of the bug — and it has a different fix.

All Environment Variables That Affect Webhook URLs

Before jumping to code, here is a clear map of every variable involved. Understanding which one does what will save you from conflicting configurations — a surprisingly common problem.

Variable Priority Comparison

Fix by Deployment Type (Choose Your Setup)

The fix is the same concept in every case, but the exact file and command differ depending on how you installed n8n. Find your setup below.

Fix A: Docker Compose (Most Common)

Open your docker-compose.yml file and add the environment variables to the n8n service block. The critical line is WEBHOOK_URL. Replace your-domain.com with your actual domain — including the trailing slash.

version: '3.8'
services:
  n8n:
    image: n8nio/n8n:latest
    restart: unless-stopped
    environment:
      - WEBHOOK_URL=https://your-domain.com/   # ← This is the critical fix
      - N8N_HOST=your-domain.com               # Fallback, keep it consistent
      - N8N_PROTOCOL=https
      - N8N_PORT=5678
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=admin
      - N8N_BASIC_AUTH_PASSWORD=your-password
    ports:
      - "127.0.0.1:5678:5678"                  # Bind to localhost only — Nginx handles public traffic
    volumes:
      - n8n_data:/home/node/.n8n
volumes:
  n8n_data:

After saving the file, apply the changes:

docker compose down && docker compose up -d

# Or if using older docker-compose command:
docker-compose down && docker-compose up -d

Fix B: .env File (systemd or pm2)

If you installed n8n with npm install -g n8n and run it as a systemd service or with pm2, your environment variables live in a .env file — typically at /home/node/.n8n/.env or wherever your n8n data folder is.

WEBHOOK_URL=https://your-domain.com/
N8N_HOST=your-domain.com
N8N_PROTOCOL=https
N8N_PORT=5678
N8N_BASIC_AUTH_ACTIVE=true
N8N_BASIC_AUTH_USER=admin
N8N_BASIC_AUTH_PASSWORD=your-secure-password

Then restart the service:

# systemd:
sudo systemctl daemon-reload
sudo systemctl restart n8n
sudo systemctl status n8n     # Verify it started cleanly

# pm2:
pm2 restart n8n
pm2 logs n8n --lines 20       # Check for startup errors

Fix C: Single Docker run Command

If you started n8n with a bare docker run command, stop the existing container and restart it with the -e flags:

docker stop n8n && docker rm n8n

docker run -d \
  --name n8n \
  --restart unless-stopped \
  -p 127.0.0.1:5678:5678 \
  -e WEBHOOK_URL=https://your-domain.com/ \
  -e N8N_HOST=your-domain.com \
  -e N8N_PROTOCOL=https \
  -e N8N_PORT=5678 \
  -v n8n_data:/home/node/.n8n \
  n8nio/n8n:latest

Fix D: Railway, Render, or Other Cloud Platforms

On cloud deployment platforms, environment variables are set through the platform dashboard, not a file. The variable name and value are the same — only the location changes.

• Railway: Project → Service → Variables → Add Variable: WEBHOOK_URL = https://your-railway-domain.up.railway.app/
• Render: Service → Environment → Add Environment Variable with the same key/value.
• Fly.io: Add to fly.toml under [env], then run fly deploy.

The Nginx Reverse Proxy Configuration (Critical Headers)

This is the part most tutorials get wrong or skip entirely. Even with WEBHOOK_URL set correctly, if your Nginx configuration does not pass the right headers, n8n may still generate incorrect URLs or refuse incoming webhook requests.

Complete Working Nginx Config for n8n

server {
    listen 80;
    server_name your-domain.com;
    # Redirect HTTP to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    # SSL — managed by Certbot / Let's Encrypt
    ssl_certificate     /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
    include             /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam         /etc/letsencrypt/ssl-dhparams.pem;

    # Increase timeout for long-running webhook responses
    proxy_read_timeout   300;
    proxy_connect_timeout 300;
    proxy_send_timeout   300;

    location / {
        proxy_pass http://127.0.0.1:5678;
        proxy_http_version 1.1;

        # ── These 4 headers are critical for n8n ──
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Real-IP         $remote_addr;

        # WebSocket support (required for n8n editor live updates)
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Disable buffering for SSE / streaming responses
        proxy_buffering off;
        proxy_cache off;
    }
}

Why Each Highlighted Header Matters

• proxy_set_header Host $host — tells n8n the actual public hostname the request arrived at. Without this, n8n sees the internal 127.0.0.1 address and may generate localhost URLs.
• proxy_set_header X-Forwarded-Proto $scheme — tells n8n whether the original request used HTTP or HTTPS. Without this, n8n generates http:// webhook URLs even though your site is on HTTPS.
• proxy_set_header X-Forwarded-For — passes the real visitor IP. Required if you use IP-based rate limiting or logging inside n8n.
• proxy_set_header X-Real-IP — similar to above, used by some n8n nodes that read the sender's IP from request headers.

After editing the Nginx config, always test before reloading:

sudo nginx -t                   # Test config for syntax errors
sudo systemctl reload nginx    # Apply if test passes

Step That Everyone Forgets: Activate the Workflow

You have set the environment variables, restarted n8n, verified the Nginx config — and the webhook still returns 404. Nine times out of ten, this is the reason: the workflow is not Active.

n8n has two URL types for webhooks:

Toggle the workflow Active using the switch in the top-right corner of the n8n editor. The switch turns green when active. At this point, the Production URL registers itself with n8n's router and will accept incoming POST requests 24/7.

How to Test Your Webhook After Fixing It

Before connecting your real external app, verify the webhook works with a controlled test. Here are three methods, from quickest to most thorough.

Method 1: cURL (Fastest)

Open a terminal on your local machine and send a POST request directly:

curl -X POST https://your-domain.com/webhook/your-path \
  -H "Content-Type: application/json" \
  -d '{"test": true, "source": "curl", "message": "Hello from TriggerWorkflow"}'

# Expected response: {"message":"Workflow was started"}

If you see {"message":"Workflow was started"}, your webhook is live and working. Switch to n8n's Execution log (left sidebar → Executions) to inspect the incoming data.

Method 2: webhook.site (Visual)

For a visual way to inspect the exact payload structure your webhook receives, use webhook.site. Set your external app to send to webhook.site temporarily, inspect the structure, then swap in your real n8n Production URL.

Method 3: Postman (Most Thorough)

Download Postman (free), create a new POST request, set the URL to your Production webhook URL, add a JSON body, and send. Postman shows you the full response headers and body — useful for debugging authentication issues.

Bonus: Test Webhooks Locally With ngrok (No VPS Needed)

If you are still in development and do not have a VPS yet — or if you want to test a new workflow without deploying to production — ngrok gives you a public HTTPS URL that tunnels directly to your local n8n instance.

Advanced Troubleshooting: When the Standard Fix Does Not Work

If you set WEBHOOK_URL, restarted, and are still seeing problems, use this diagnostic table. These are the ten real-world failure scenarios I have personally debugged across different VPS providers and deployment setups.

How to Verify the Variable Was Actually Applied

Never assume the restart worked. Verify the variable is live inside the running container or process:

# Docker:
docker exec n8n env | grep -E "WEBHOOK|N8N_HOST|N8N_PROTOCOL"

# systemd — check what the process sees:
sudo systemctl show n8n --property=Environment

# Expected output should include:
WEBHOOK_URL=https://your-domain.com/

Oracle Cloud Free Tier: Extra Step Required

Oracle Cloud's free tier is popular for self-hosting n8n because it is genuinely free with no credit card expiry catch. But it has one networking quirk that catches almost everyone: two separate firewalls.

The Two Firewalls Problem

Most VPS providers have one firewall. Oracle Cloud has two:

1. OS-level firewall (iptables / ufw) — the one you configure with sudo ufw allow 443.
2. Oracle Security List (in the Oracle Cloud Console web UI) — a separate network-level firewall that sits in front of your instance.

If you only open port 443 in the OS firewall but forget the Oracle Security List, HTTPS traffic never even reaches your server. The webhook error persists regardless of any n8n configuration.

Frequently Asked Questions

Continue Learning on TriggerWorkflow