n8n Reverse Proxy Webhook Setup

n8n running behind Nginx, Caddy, or Cloudflare works fine for browsing the editor, right up until you actually try to use a webhook and it either points to localhost:5678 in the UI or fails entirely from the outside. This is one of the most common self-hosted setup snags, and it comes down to a handful of environment variables n8n needs to correctly understand what URL the outside world actually sees, since the reverse proxy sits between n8n and the internet and n8n has no way to know about it unless you tell it.

I fix this on nearly every self-hosted n8n instance that has been put behind a reverse proxy without these specific settings configured, since the default behavior assumes n8n is reachable directly rather than through a proxy layer. This post covers exactly which settings matter, why WebSocket connections need special handling, and the errors that show up when something is still misconfigured.

Why Put n8n Behind a Reverse Proxy?

A reverse proxy handles TLS termination, routes multiple services on the same server through clean subdomains, and lets you put n8n behind HTTPS without n8n itself managing certificates. This is standard practice for any self-hosted service exposed to the internet, and n8n is no exception, but it requires n8n to be told explicitly what URL the outside world is actually using, since internally n8n only knows it is running on its own local port.

Domain and HTTPS

n8n constructs its webhook URL by default from N8N_PROTOCOL, N8N_HOST, and N8N_PORT. Behind a reverse proxy, that default construction is wrong, because n8n is running internally on port 5678 while the proxy exposes it to the world on port 443. Left unconfigured, this is exactly what produces a webhook URL displayed in the editor as http://localhost:5678/..., unreachable from anywhere outside the server itself.

Nginx/Proxy Architecture

The fix is setting N8N_WEBHOOK_URL explicitly to the actual public-facing URL, the domain and protocol the outside world uses to reach n8n. This environment variable replaces the older WEBHOOK_URL variable, which is deprecated and will still work but logs a deprecation warning if you use it, worth updating to the current variable name in any newer setup. Set N8N_PROXY_HOPS to 1 for a single reverse proxy in front of n8n, or higher if there is an additional layer, such as a cloud load balancer sitting in front of the reverse proxy itself.

Webhook URLs

With N8N_WEBHOOK_URL set correctly, both the URL displayed in the editor and the URLs n8n registers with external services when you set up an OAuth-based credential will use the correct public domain rather than defaulting to localhost. This matters beyond just webhooks specifically, since OAuth redirect URLs depend on the same setting, and a misconfigured value here is a common cause of OAuth credential setup silently failing with a redirect pointing nowhere reachable.

Forwarded Headers

On the reverse proxy itself, forward the headers that tell n8n about the original request: X-Forwarded-Proto so n8n knows the original request was HTTPS even though the proxy may be talking to n8n over plain HTTP internally, and the standard forwarded headers your proxy software provides by default. Missing these headers is what causes n8n to believe requests are arriving over HTTP even when the outside world is correctly using HTTPS, which can cascade into other subtle issues depending on how strictly other settings are configured.

Beyond the URL and header settings, n8n's editor relies on a WebSocket connection for real-time updates, and Nginx specifically needs explicit configuration to support the WebSocket upgrade handshake, since it does not do this by default the way some other proxy software does. Missing this specific configuration produces a WebSocket connection failure visible in the browser console, along with symptoms like the editor failing to properly stop listening for a test webhook call, even though regular page loads work fine.

Proxy Timeouts

If your workflows include steps that legitimately take a while, long-running API calls, large file processing, check that your reverse proxy's timeout settings are not cutting off connections before n8n has finished responding. A proxy timeout that is shorter than a genuinely long-running webhook execution produces a failure that looks like it originates in n8n but is actually the proxy giving up first.

Common 404 and 502 Errors

404 on a webhook URL that looks correct. Usually the webhook URL displayed in the editor does not match what N8N_WEBHOOK_URL was actually set to, often because the environment variable was changed after n8n was already running and the container was not restarted to pick up the new value.

502 from the proxy. Typically a proxy configuration issue rather than an n8n issue, either the proxy is pointing at the wrong internal port or address for n8n, or n8n itself is not actually running or reachable on the port the proxy expects.

Editor loads but webhooks intermittently fail. Check the WebSocket configuration on the proxy specifically, since a broken WebSocket connection can cause n8n's real-time features to behave unpredictably even while basic page loads succeed.

If you are running n8n in queue mode behind a reverse proxy, covered in n8n Queue Mode, make sure the webhook-handling process specifically, not just the main editor process, has the correct URL and proxy settings applied, since a queue-mode deployment can have webhook handling split across a dedicated process.

Production Testing

Before relying on this in production, test a real webhook call from outside your network, not just from the server itself, using curl or an actual external service pointed at the public URL. A webhook that works when tested from inside the same network as the server can still fail from genuinely external traffic if a proxy or firewall setting is only correctly configured for internal access.

If your self-hosted n8n instance behind a reverse proxy is showing broken webhook URLs, OAuth redirect failures, or WebSocket errors in the editor, that is exactly the kind of infrastructure fix I take on for clients. Book a free 30-minute call and bring your current proxy setup, and we will get it configured correctly.

Frequently Asked Questions

Can n8n run behind a reverse proxy?

Yes, this is a standard and common setup, but n8n needs to be told explicitly what public URL the outside world uses through the N8N_WEBHOOK_URL environment variable, since it cannot infer this automatically from behind a proxy.

Why is my n8n webhook returning 404?

Usually because the webhook URL n8n is using internally does not match what is actually reachable from outside, often caused by N8N_WEBHOOK_URL being unset, set incorrectly, or changed without restarting the n8n container to pick up the new value.

Why does n8n webhook return 502?

Typically a proxy configuration issue rather than an n8n problem: the reverse proxy is pointing at the wrong internal address or port for n8n, or n8n is not actually running or reachable where the proxy expects it to be.

How do I enable HTTPS for n8n?

Terminate TLS at the reverse proxy layer using a certificate from Let's Encrypt or another provider, and forward the X-Forwarded-Proto header to n8n so it correctly understands the original request was made over HTTPS.

Does n8n need special proxy headers?

Yes. Forward X-Forwarded-Proto so n8n knows the original protocol, and configure WebSocket upgrade support specifically on the proxy, since Nginx in particular does not enable this by default and n8n's editor relies on it for real-time updates.

How do I configure n8n webhooks behind Nginx?

Set N8N_WEBHOOK_URL to your public-facing domain and protocol, set N8N_PROXY_HOPS to reflect how many proxy layers sit in front of n8n, forward the correct headers including X-Forwarded-Proto, and add explicit WebSocket upgrade configuration in the Nginx config.

If you would rather have this configured than configure it yourself, I take on n8n self-hosted infrastructure work through Fiverr.