HOKIO / DEVELOPER GUIDES
Give self-hosted n8n a permanent public webhook URL
Disclosure: this article is written by the team behind Hokio, a webhook relay for local applications. The n8n configuration below was tested end-to-end and works with any tunnel or relay, not only ours. Where our product is the subject, we say so and state its limits.
The problem: your webhook URL keeps dying
If you run n8n in Docker on your own machine — a workstation, a homelab box, a small VPS — and an external service needs to POST into one of your workflows, you have a reachability problem. n8n listens on localhost:5678. The internet cannot see localhost. So you open a tunnel, get a public URL, paste it into the sender's configuration, publish your workflow, and everything works.
Until the tunnel restarts.
Most free and cheap tunnel tools hand out ephemeral hostnames. Restart the tunnel agent, reboot the machine, or let a free session time out, and the URL changes. The consequences cascade:
- Every sender that stored the old URL now delivers into a dead address. You reconfigure each one — some of which are SaaS dashboards you no longer control easily.
- n8n itself bakes the webhook base URL into the node configuration shown in the editor and into the URLs your workflows generate. When the public base changes, you re-set the environment variable, recreate the container, and re-publish affected workflows.
- Test versus production path confusion piles on top: n8n serves test listeners under
/webhook-test/...and published workflows under/webhook/..., and both paths need to stay reachable through whatever tunnel you run.
For a one-off demo, none of this matters. For an automation that a client's form tool posts into every day, an address that changes weekly is not a production endpoint. It is a recurring outage you perform by hand.
There is a second failure mode that is quieter and worse: exposing too much. Pointing a tunnel at port 5678 exposes the entire n8n application — the editor, the REST API, the credential management endpoints — unless the tunnel layer restricts paths. Setting a public webhook base URL does not make the editor private by itself. The fix is to restrict the public surface to POST and the exact webhook paths, and nothing else.
The local half: a tested Docker Compose setup
This is the configuration we tested on n8n 2.45.7 in Docker on an Ubuntu/WSL machine on 31 October 2026. It binds n8n to the host's loopback interface only, so the public surface is whatever tunnel or relay you attach — never the Docker network directly.
Save this as compose.yaml:
services:
n8n:
image: docker.n8n.io/n8nio/n8n:stable
ports:
- "127.0.0.1:5678:5678"
volumes:
- hokio_n8n_demo:/home/node/.n8n
environment:
N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS: "true"
GENERIC_TIMEZONE: "Etc/UTC"
TZ: "Etc/UTC"
volumes:
hokio_n8n_demo:
docker compose up -d
Open http://localhost:5678, create the local owner account, and confirm the editor works. Two notes from the test: the stable tag changes over time, so pin a reviewed version for repeatable deployments; and do not delete the named volume when recreating the container — that is your n8n data, including credentials.
If you already run n8n, do not start a replacement instance. Keep the existing data volume and configuration and adapt the environment instead.
Tell n8n its public webhook base URL
Whatever public hostname you settle on — tunnel-provided or permanent — n8n needs to know about it so webhook nodes display and generate the right URLs. Add this under environment in the Compose file, replacing the placeholder with your actual hostname:
N8N_WEBHOOK_URL: "https://YOUR_ASSIGNED_HOKIO_HOST/"
Then recreate:
docker compose up -d
Four details that cost people an afternoon each:
- Variable name. Current n8n uses
N8N_WEBHOOK_URL. Older releases useWEBHOOK_URL; that name is deprecated from n8n 2.35.0. Use the variable supported by your installed release — not both. - Trailing slash. Keep it. If the editor still shows localhost URLs in webhook nodes, the base origin is usually missing the trailing slash, the wrong variable is set, or the container was restarted instead of recreated.
- Recreate, don't restart. A plain container restart does not apply edited Compose values.
docker compose up -drecreates the container with the new environment. N8N_PROXY_HOPSis not a talisman. Proxy trust settings depend on your actual forwarding chain. Do not blindly copyN8N_PROXY_HOPS=1or trust client-supplied forwarding headers.
Restrict the public surface
Before the URL is shared with anything, restrict what passes through it. With Hokio this is a per-link policy: allowed HTTP methods, allowed paths, source IP/CIDR allowlists, and rate/concurrency/body-size limits on each endpoint. For the demo workflow, allow only POST and the two exact paths:
/webhook-test/hokio-demo(during development)/webhook/hokio-demo(after publishing)
Block the editor, REST, and credential-management paths. Remove the test path from the allowlist after development. If your tunnel tool cannot restrict by path and method, point it at a reverse proxy that can — otherwise you are exposing the whole n8n application to the internet.
Build and test the workflow
Create a workflow with a Webhook trigger: HTTP Method POST, Path hokio-demo, response mode set to respond immediately for a harmless first test. Save this synthetic event as event.json:
{"event":"task.completed","job_id":"demo-001","status":"completed"}
Test on localhost first, then through the public URL (use curl.exe in Windows PowerShell):
curl -i -X POST http://127.0.0.1:5678/webhook-test/hokio-demo -H "Content-Type: application/json" --data-binary @event.json
curl -i -X POST https://YOUR_ASSIGNED_HOKIO_HOST/webhook-test/hokio-demo -H "Content-Type: application/json" --data-binary @event.json
The test listener may expire or stop after one event — re-arm it before the second request. Then publish the workflow (older versions use an Active toggle; n8n 2.45.7 asks for a version name in a Publish confirmation dialog) and switch to the production path:
curl -i -X POST https://YOUR_ASSIGNED_HOKIO_HOST/webhook/hokio-demo -H "Content-Type: application/json" --data-binary @event.json
Production events appear in Executions, not in the test listener. With the immediate-response setting, the demo returns HTTP 200 and {"message":"Workflow was started"} — confirm Succeeded in Executions, because an HTTP acknowledgement proves receipt, not that later steps completed. Before real traffic, configure Header Auth or another supported authentication method on the Webhook node, and validate the sender's signed raw payload if it signs.
The permanence half
The steps above work with any tunnel. What a permanent relay adds is that the address stops being a variable. Hokio assigns each endpoint an HTTPS URL under *.hooks.hokio.top; the connector on your machine opens a single outbound WebSocket to the relay — no port forwarding, no inbound firewall holes — and the URL survives agent reconnects and moves between relay nodes. In the recorded verification, published production requests succeeded before and after reconnecting the connector, with executions visible in n8n.
The original Webhook connector remains supported. On Linux, its commands are:
curl -fsSL https://hokio.dev/static/downloads/install-legacy.sh | sh
hokio-agent login --panel-url https://hokio.dev --port 5678 --connect
Windows users can install the legacy Webhook client from the Microsoft Store and select port 5678 in the app. For the native Webhook and URL preview, use the native download, run hokio setup, select Webhook and port 5678, then run hokio run (Windows: .\hokio.exe). Both versions require the same restricted endpoint policy. See the updated connection guide.
Honest boundaries
Stated before a skeptic finds them:
- No offline queueing. While your machine is offline, the URL stays assigned but requests return unavailable; the sender gets a failure and must retry. We do not queue events for later delivery, and any tool that claims otherwise for a laptop-backed endpoint deserves scrutiny.
- Per-link policy restrictions are real restrictions. Requests outside the allowed methods, paths, source IPs, or limits are denied. That is the point, but it also means a misconfigured policy looks like an outage. The troubleshooting step is checking the policy, not loosening it to "allow everything."
- Authentication and signature verification are your workflow's job. The relay delivers; it does not authenticate senders on your behalf beyond the policy rules you set.
- The platform is young. It is invitation-gated today, runs on modest infrastructure, and offers no SLA. Prices are published (Starter $5/mo, Builder $19/mo, Scale $79/mo; 14-day card-upfront trial on the entry tiers).
Try it without an account
The local half of every step above — the Compose file, N8N_WEBHOOK_URL, the workflow, the curl tests — runs without a Hokio account. The full walkthrough with a downloadable tested workflow JSON is at hokio.dev/guides/n8n-local-webhooks, alongside guides for Express, FastAPI, and a dependency-free Python receiver. If you want a permanent URL for the setup, request access. Eligible trials require a payment method at secure checkout and billing starts after the displayed trial end unless cancelled first.
Official references: n8n Docker installation, webhook base URL configuration, and the n8n Webhook node.
Keep building.
Browse all webhook integration guides →
Installation and connection help in the webhook quick start →