Run n8n Locally with Secure Public Webhooks

Why localhost webhooks need a public request path

When n8n runs on a workstation, home server, or private lab device, it commonly listens on a local address such as http://localhost:5678. The word localhost always refers to the machine making the request. If a remote webhook provider calls that address, it tries to connect to port 5678 on its own infrastructure rather than on your n8n host.

A private LAN address has a related limitation. It may be reachable from other devices on the same network, but it is not normally routable from the public internet. Network address translation, router rules, firewalls, and the absence of a public IP can prevent unsolicited inbound requests from reaching the service.

Webhook providers therefore need a public callback URL. They store that URL and make an HTTP request when an event occurs. The URL must reach the correct n8n Webhook node path, and the request method must match the method selected in that node.

With Localtonet, our client runs on a device that can reach n8n and establishes an outbound connection to a Localtonet relay server. An HTTP tunnel supplies a public URL and forwards requests arriving there to the configured local IP address and port. This workflow does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address.

A successful request follows four stages. The provider sends a request to the public HTTPS URL, the Localtonet relay accepts it, the running tunnel carries it to the selected client, and the client forwards it to n8n. n8n then looks for a registered webhook with the same test or production path and HTTP method.

Prerequisites and deployment scope

This tutorial covers one reproducible installation path: self-hosted n8n running in Docker Compose on the same machine as the Localtonet client. n8n also supports self-hosting through Docker, npm, Docker Compose, and supported platforms, but startup commands and persistence differ among those methods. Limiting the implementation to Docker Compose lets us show the complete configuration without mixing incompatible instructions.

Before starting, prepare the following:

• A computer that can remain awake and connected while webhook requests are expected.
• Docker Engine or Docker Desktop with the Docker Compose command available.
• A browser and terminal access on the host.
• A Localtonet account and the Localtonet client for the host operating system.
• Permission to register or change the callback URL at the external webhook provider.
• A non-sensitive sample event for testing.

The Docker Compose configuration below publishes container port 5678 on host port 5678 and stores n8n data in a named volume. The named volume is important because removing and recreating a container must not remove workflows, credentials, or instance configuration stored under n8n's data directory.

n8n's official deployment overview explains the distinction between managed n8n Cloud and self-hosted installations. This article specifically uses the self-hosted model described in the n8n deployment documentation.

Run n8n locally with Docker Compose

Start by running n8n without a public webhook override. This gives you a known-good local service before adding tunnel configuration. Separating local application verification from public connectivity makes later failures much easier to diagnose.

Create and enter the project directory:

mkdir n8n-local
cd n8n-local

Save the following as compose.yaml:

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    ports:
      - "5678:5678"
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:

Start n8n and confirm that the container is running:

docker compose up -d
docker compose ps

Open http://localhost:5678 in a browser on the Docker host. Complete n8n's initial setup if prompted. You can also inspect startup output with:

docker compose logs n8n

At this stage, the browser should reach n8n locally. If it cannot, do not proceed to the public tunnel. Check the container status, logs, published port, and whether another process already uses port 5678.

When the Localtonet client will run on another device, localhost on that device will not refer to the Docker host. In that topology, n8n must be reachable through an appropriate LAN address from the client device. Test that exact address from the client's network context before configuring the tunnel.

Create and start the Localtonet HTTP tunnel

Localtonet's HTTP tunnel configuration points to the local IP address and port where n8n is reachable. For the same-host Docker Compose setup above, that target is normally 127.0.0.1 on port 5678 because Docker publishes the container port on the host.

Follow the documented product sequence below. Current relay choices, region availability, process-type availability, and plan capabilities must be taken from the dashboard rather than copied from a hardcoded example.

Keep the complete public base URL, including https://, available for the next step. Consult the Localtonet HTTP tunnel documentation when confirming current dashboard options.

Configure n8n's WEBHOOK_URL and persist it

A working tunnel does not automatically change the URLs generated by n8n. Without an override, a self-hosted instance may continue displaying webhook URLs based on its internal localhost address. n8n uses the WEBHOOK_URL environment variable to define the externally reachable base URL for webhook generation.

Add the variable to the Compose file rather than setting it only in an interactive shell. A value placed only in a temporary shell can disappear after logout, restart, container recreation, or host reboot. Compose configuration and a project .env file provide a repeatable way to recreate the container with the same public base address.

Update the n8n service in compose.yaml:

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    ports:
      - "5678:5678"
    environment:
      - WEBHOOK_URL=${WEBHOOK_URL}
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:

In the same directory, create a file named .env. Replace the example hostname with the exact public HTTPS base URL assigned to your tunnel:

WEBHOOK_URL=https://your-public-host.example/

The hostname above is intentionally a placeholder and will not work as written. Use the Localtonet URL shown for your running tunnel. Keep the trailing slash so n8n can combine the base address with its webhook paths cleanly.

Recreate the service so the container receives the new environment variable:

docker compose up -d --force-recreate
docker compose ps

The named n8n_data volume remains attached when Compose recreates the container. Recreating the container is different from deleting the named volume. Do not remove that volume unless you intentionally want to remove the stored n8n data associated with it.

Verify that the variable is present without printing unrelated environment values:

docker compose exec n8n printenv WEBHOOK_URL

Then open a workflow, add a Webhook node, and inspect both URLs displayed at the top of the node panel. They should begin with the Localtonet HTTPS address rather than http://localhost:5678. If they do not, verify the spelling of WEBHOOK_URL, confirm that Compose loaded the expected project files, and recreate the container again.

Configure test and production webhooks correctly

The n8n Webhook node provides separate test and production URLs. Select Test URL or Production URL in the node panel to see the appropriate address. These are separate routes with different registration behavior, so they are not interchangeable.

According to the n8n Webhook node documentation, n8n registers a test webhook when you select Listen for Test Event or execute an inactive workflow in the applicable development flow. The incoming data appears in the workflow editor. This listener is temporary, so a provider calling the test URL later may find that no test webhook is registered.

n8n registers the production webhook when you publish the workflow. Production requests do not display their data in the editor as a test event. Open the workflow's Executions tab and select the relevant execution to inspect the input and result.

Create a minimal POST webhook

For a controlled first test, create a workflow with a Webhook node and use these values:

• HTTP Method: POST
• Path: localtonet-check
• Authentication: None for this isolated non-secret connectivity test only
• Respond: Respond Immediately

The Webhook node supports DELETE, GET, HEAD, PATCH, POST, and PUT. The sender and node must use the same method. A POST request sent to a node configured for GET is not an equivalent test.

The path can be generated by n8n or set manually. Manually selecting a stable path can be useful when a provider needs a consistent route, but path secrecy is not authentication. Use an authentication or signature-validation mechanism before allowing a webhook to perform sensitive actions.

Understand response modes

The response mode affects both what the provider receives and how long it may need to wait:

• Respond Immediately returns the configured response code and the message Workflow got started after the workflow begins.
• When Last Node Finishes waits for workflow processing and can return output from the last node.
• Using Respond to Webhook Node lets the workflow define the response through a dedicated Respond to Webhook node.
• Streaming response supports real-time output when the workflow contains nodes with streaming support.

A provider with a short acknowledgement deadline may retry or mark delivery as failed if the webhook waits for a long workflow. Respond Immediately is useful when the provider only needs prompt acceptance, while the other modes suit integrations that genuinely require calculated response data. Return only the data the caller needs because workflow output can contain internal values.

Know the payload limit

The default n8n webhook maximum payload size is 16 MB. A larger request can fail before the workflow handles it. For self-hosted n8n, the documented override is the N8N_PAYLOAD_SIZE_MAX environment variable. If an integration requires a different limit, add that variable to the persistent Compose environment using a value supported by current n8n documentation, recreate the container, and retest with a controlled payload.

Raising a payload limit increases the amount of request data the service may need to receive and process. Confirm that the provider's own limit, Localtonet account capabilities, available memory, workflow behavior, and timeout requirements are also suitable. Do not raise a limit merely to mask an unexpected oversized request.

Verify the webhook from end to end

A complete verification proves more than public reachability. It confirms local n8n availability, the active tunnel, the generated public base URL, the selected webhook mode, the HTTP method, the path, the response, and the resulting n8n execution.

Test the temporary test URL

1. Open the Webhook node and select its test URL.
2. Select Listen for Test Event.
3. Copy the complete generated test URL. It should start with the Localtonet HTTPS hostname.
4. Send the non-secret request below while the listener is active.

curl -i -X POST "https://your-public-host.example/webhook-test/localtonet-check" \
  -H "Content-Type: application/json" \
  -d '{"event":"localtonet-check","id":"demo-001","secret":false}'

Replace the entire sample URL with the exact test URL displayed by n8n. Do not assume the route shown in the example if n8n generated a different path.

With Respond Immediately and the default successful response configuration, expect a successful HTTP response and the message Workflow got started. The editor should display the captured request data, including the sample event and id values. A customized response code or body will change the HTTP output, so compare it with the node's actual response settings.

Test the production URL

1. Publish the workflow so n8n registers its production webhook.
2. Select and copy the production URL from the Webhook node.
3. Send the same sample JSON to that production URL.
4. Open the workflow's Executions tab and inspect the new production execution.

curl -i -X POST "https://your-public-host.example/webhook/localtonet-check" \
  -H "Content-Type: application/json" \
  -d '{"event":"localtonet-check","id":"demo-002","secret":false}'

The exact production path must come from the node. A successful HTTP response without the expected execution can indicate a route mismatch, response from another handler, or a workflow condition that prevented normal processing. Inspect the execution history and n8n logs rather than relying only on the caller's status code.

Check for unintended public routes

Open the public base URL without the webhook path in a private browser window. Also inspect its headers from the terminal:

curl -I "https://your-public-host.example/"

A response that redirects to or displays the n8n sign-in page proves that the tunnel exposes more than the workflow callback. Even when n8n requires login, the editor-facing service is still internet-reachable. Authentication reduces unauthorized use, but it does not make the route private.

This behavior is expected from a basic tunnel pointed at n8n's service root. Localtonet forwards requests to the configured service and does not automatically add path-level isolation. If your requirement is public webhook paths with a private editor, place a correctly configured reverse proxy in front of n8n and tunnel to that proxy, or use another deployment architecture that explicitly separates those routes. Reverse-proxy path-filter configuration is environment-specific and is outside the setup scope of this article.

Secure public n8n webhook traffic

Public reachability and request authorization are separate concerns. Localtonet provides the route to n8n, while n8n and the workflow must decide whether a request is allowed and trustworthy. Treat every request body, header, parameter, and query value as untrusted input.

Authentication and signatures are not interchangeable

Webhook node authentication controls whether the caller can satisfy the credential mechanism configured in n8n. Provider signature verification checks whether the message was signed using the provider's documented scheme, often including the raw body, a timestamp, and a shared secret or public key.

Do not replace provider-specific verification with a check that merely confirms a header exists. Verify the calculated signature, use constant-time comparison where required by the provider's algorithm, reject stale timestamps when the protocol supports them, and preserve the raw body if the signature specification requires byte-for-byte verification. n8n's Webhook node provides a Raw Body option for cases where raw request data is needed.

Apply request restrictions in layers

n8n can restrict a Webhook node with an IP allowlist. Addresses outside the configured list receive a 403 response. This is useful only when the sender publishes reliable source ranges and uses them consistently. It is a poor fit for providers with dynamic, incomplete, or undocumented egress addresses.

n8n also provides an Only Run If expression. It can evaluate the request body, headers, path parameters, or query values and run the workflow only when the expression is true. This option runs after IP allowlist and authentication checks. It can reduce unnecessary executions, but it should not replace cryptographic authentication. The documented behavior also allows a request through if the expression itself fails to evaluate, so do not treat it as the sole security boundary.

Protect credentials and operational data

• Keep the Localtonet device AuthToken out of n8n workflow input and output.
• Store provider credentials and webhook secrets using appropriate credential or secret-management facilities.
• Do not paste real customer events into documentation, screenshots, issue trackers, or chat messages.
• Avoid returning raw downstream errors to the webhook caller.
• Review execution retention and logs for sensitive payloads.
• Use non-sensitive synthetic events for routine health checks.

Operations, lifecycle, and troubleshooting

Troubleshoot from the inside out. Start with the local n8n process, then the container network, Localtonet client, tunnel state, generated URL, webhook registration, provider request, and workflow execution. This order prevents an application failure from being mistaken for a tunneling problem.

Local reachability and container networking

If the Localtonet client and Docker run on the same host, test http://127.0.0.1:5678 from that host. If the client runs elsewhere, test the Docker host's reachable LAN address from the client device. A successful browser request from your laptop does not prove that another device can reach the same target.

Do not point Localtonet at a container-only address unless the client actually shares the relevant container network and that topology is intentional. The Compose file in this guide publishes n8n on the host specifically so the host-side Localtonet client can reach it.

Test listener and production registration

A test webhook is temporary. If a test worked once and later returns an unregistered-webhook response, reactivate Listen for Test Event. For repeated callbacks, publish the workflow and configure the provider with the production URL instead.

After changing a Webhook node's path or method, copy its URL again and update the provider. Do not assume that editing the node automatically updates callback registrations stored on an external platform.

Stable callback management

Many providers retain a callback until an administrator changes it. A generated random subdomain can be convenient for a short development session, but do not assume that a replacement tunnel will receive the same hostname. Where available and appropriate, a Custom Sub Domain or Custom Domain can provide a deliberately selected public name. Confirm current product and plan availability before relying on either option, and consult current Localtonet documentation before changing DNS records.

Maintain a small callback inventory for long-lived integrations. Record the provider, workflow, node, test or production mode, public hostname, HTTP method, authentication scheme, owner, and last verification date. Do not record secrets in that inventory.

Stopping and deleting the tunnel

Stop the tunnel when temporary public access is no longer required. Delete it when the configuration will not be reused. The public route is available only while the selected client is connected and the tunnel is running.

Stopping a tunnel does not remove a callback URL stored by an external provider. Disable or update that registration too, especially if the provider will continue retrying failed requests. If a public hostname is retired, remove it from WEBHOOK_URL or replace it with the next intended address before recreating n8n.

Frequently asked questions