How to Test n8n Webhooks Locally with Tunnelmole

Introduction to n8n and Webhooks

In the world of workflow automation, n8n has emerged as a powerful, flexible, and developer-friendly tool. It allows you to connect various applications and services to create sophisticated automated workflows with minimal code. A core component of these workflows, and indeed of modern web services, is the webhook.

So, what is an n8n webhook?

A webhook is essentially a way for applications to send automated messages or information to other applications. It's like an API but in reverse. Instead of your application actively polling a service for new data (making a request), the service automatically sends data to your application's unique "webhook URL" the moment an event occurs.

In n8n, the "Webhook" node acts as a trigger, initiating a workflow whenever it receives an HTTP request. This is incredibly useful for a vast range of scenarios:

• Receiving notifications from a payment gateway like Stripe after a successful transaction.
• Kicking off a customer onboarding sequence when a new user signs up in your CRM.
• Integrating with Git platforms like GitHub or GitLab to automate CI/CD pipelines.
• Connecting to IoT devices that send status updates.

The problem arises when you are developing and testing these workflows. Your n8n instance is likely running on your local machine (localhost), which is not accessible from the public internet. External services like Stripe or GitHub cannot send their webhook notifications to a localhost address.

This guide will walk you through the solution: using an open-source tunneling tool called Tunnelmole to expose your local n8n instance to the internet with a public URL, making n8n webhook testing a breeze.

The Challenge: Testing n8n Webhooks Locally

When you're building a workflow in n8n, you need to test it thoroughly. For a webhook-triggered workflow, this means you need a way to send test requests to your n8n Webhook node.

Let's imagine you've set up a new workflow. You add a Webhook node, and n8n generates two URLs for you: a Test URL and a Production URL.

These URLs will look something like this: http://localhost:5678/webhook-test/d8f8a1b2-c3d4-e5f6-g7h8-i9j0k1l2m3n4

While you are on the same machine, you can use a tool like curl or Postman to send a POST request to this localhost URL and see your workflow execute.

curl -X POST -H "Content-Type: application/json" -d '{"message":"hello world"}' http://localhost:5678/webhook-test/d8f8a1b2-c3d4-e5f6-g7h8-i9j0k1l2m3n4

This is fine for initial, manual testing. But what happens when you need to integrate with a real-world, third-party service? You can't give Shopify, Stripe, or GitHub your localhost URL. They need a public, internet-accessible HTTPS endpoint.

This is where many developers get stuck. The traditional solutions are clunky:

1. Deploy every time: You could deploy your n8n instance to a cloud server every time you make a small change. This is slow, inefficient, and clutters your development process.
2. Mocking services: You could use tools to mock the webhook requests. This can be complex to set up and may not accurately replicate the behavior of the actual service, leading to bugs in production.

There must be a better way. And there is.

The Solution: Exposing Your Local Server with Tunnelmole

The most efficient way to solve this problem is to give your local n8n instance a temporary public URL. This is where Tunnelmole comes in.

Tunnelmole is a simple, open-source command-line tool that creates a secure tunnel between your local machine and a public server. It effectively forwards all requests from a public URL to your local n8n instance.

This means you can:

• Test end-to-end: Use the actual third-party service to send webhooks directly to your local development environment.
• Debug in real-time: Set breakpoints in your custom n8n nodes or function nodes and inspect the live data coming from the webhook.
• Get fast feedback: Share your work-in-progress with colleagues or clients without deploying it.
• Avoid complex configurations: No need to mess with firewalls, NAT, or complex network settings.

One of the key advantages of Tunnelmole is that it's open source and self-hostable. While you can use the managed service for convenience, you have the freedom to inspect the code and even host the tunnel server yourself for maximum control and privacy.

How Tunnelmole Works

The concept is straightforward. The Tunnelmole client, running on your machine, establishes a persistent connection to a public Tunnelmole server. When an external service sends a request to your public Tunnelmole URL, the server forwards that request through the established tunnel to the client, which then passes it on to your local n8n instance on localhost.

This entire process happens in milliseconds, allowing for a seamless development experience.

Step-by-Step Guide: Testing Your n8n Webhook with Tunnelmole

Let's get our hands dirty and walk through the process from start to finish.

Step 1: Set Up a Basic n8n Workflow

First, ensure you have n8n running. You can run it via Docker, npm, or n8n Desktop. For this example, let's assume it's running and accessible at http://localhost:5678.

1. Open your n8n canvas and create a new workflow.
2. Click the + button to add a new node.
3. Search for and select the "Webhook" trigger node.

4. This node will automatically be configured. In the properties panel on the right, you'll see the "Test URL" and "Production URL". For development, we'll use the Test URL. Copy it.

   Your Test URL will be something like: http://localhost:5678/webhook-test/your-unique-path

5. Next, add another node to see the workflow in action. A "Respond to Webhook" node is perfect for this. Connect the Webhook node to the "Respond to Webhook" node.

6. In the "Respond to Webhook" node's properties, you can set a response body. Let's add a simple JSON response:
   

   {
     "status": "success",
     "message": "Webhook received!"
   }
   

Step 2: Install Tunnelmole

Installing Tunnelmole is a one-line command. It's a native NodeJS application, but you can also install a pre-compiled binary if you don't have Node.js installed.

For Linux, Mac, or Windows Subsystem for Linux (WSL):

Open your terminal and run the following command. It will download an installation script and execute it, which detects your OS and installs the correct binary.

curl -O https://install.tunnelmole.com/xD345/install && sudo bash install

For Windows:

Download tmole.exe and place it in a directory that is part of your system's PATH.

With NPM:

If you have Node.js (version 16.10 or later), you can install it globally via npm:

sudo npm install -g tunnelmole

Step 3: Get a Public URL for Your n8n Instance

This is the magic step. Your n8n instance is running on port 5678.

1. Open a new terminal window (leave n8n running in its own).

2. Run the following command:
   

   tmole 5678
   

3. Tunnelmole will connect to the service and generate your public URLs. The output will look like this:
   

   $ tmole 5678
   Your Tunnelmole Public URLs are below and are accessible internet wide. Always use HTTPs for the best security
   
   https://cqcu2t-ip-49-185-26-79.tunnelmole.net ⟶ http://localhost:5678
   http://cqcu2t-ip-49-185-26-79.tunnelmole.net ⟶ http://localhost:5678
   

You now have a public HTTPS URL! In this example, it's https://cqcu2t-ip-49-185-26-79.tunnelmole.net. Yours will be different.

Step 4: Trigger Your n8n Webhook from the Internet

Now we'll combine the Tunnelmole URL and the n8n Webhook URL.

• Tunnelmole URL: https://<your-subdomain>.tunnelmole.net
• n8n Webhook Path: /webhook-test/your-unique-path

Combine them to create your final public webhook URL: https://<your-subdomain>.tunnelmole.net/webhook-test/your-unique-path

Now, let's trigger it.

1. In your n8n canvas, click the "Execute Workflow" button. The Webhook node will now be listening for a test request.

2. Go to your terminal (or use an API client like Postman) and use curl to send a request to your new public URL. Make sure to send some JSON data with the -d flag.
   

   curl -X POST -H "Content-Type: application/json" -d '{"customer_id": 123, "event": "new_order"}' https://<your-subdomain>.tunnelmole.net/webhook-test/your-unique-path
   

   Remember to replace the URL with your actual Tunnelmole URL.

3. When you send this request, curl will receive the response you configured in the "Respond to Webhook" node:
   

   {
     "status": "success",
     "message": "Webhook received!"
   }
   

4. Switch back to your n8n canvas. You should see that the workflow has executed successfully! Click on the Webhook node and inspect the "Output" tab. You'll see the JSON data you sent via curl, neatly parsed and ready to be used in subsequent nodes.

That's it! You have successfully tested a local n8n webhook using a public URL provided by Tunnelmole. You can now configure any third-party service to send webhooks to this URL, and they will be received by your local n8n instance.

Advanced Usage and Considerations

Custom Subdomains

The randomly generated URLs from Tunnelmole are great for quick tests, but sometimes you need a persistent URL that doesn't change every time you restart the tool. This is useful if you need to repeatedly configure a third-party service with your webhook URL.

Tunnelmole supports custom subdomains. You can run it with the as argument:

tmole 5678 as my-n8n-workflow.tunnelmole.net

Using the hosted Tunnelmole service requires a subscription for custom subdomains. Alternatively, because Tunnelmole is open source, you can self-host the service and use custom domains for free. You can find the server code and instructions on the Tunnelmole Service GitHub repository.

Security

When you expose a local service to the internet, even temporarily, security is important.

• Use Production URLs in n8n: When moving towards production, use the "Production URL" from the n8n Webhook node. These URLs remain active even when you're not manually executing the workflow in the editor.
• Webhook Authentication: The n8n Webhook node has built-in features for authentication. You can use Header Auth, Query Auth, or even a custom authentication method to ensure that only legitimate services can trigger your workflow.

Conclusion

Testing n8n webhook integrations no longer needs to be a roadblock in your development process. By combining the power of n8n's local instance with the simplicity of Tunnelmole, you can create a seamless and efficient workflow. You can now build, test, and debug complex automations that rely on external services, all from the comfort of your local machine.

The key takeaways are:

• Webhooks are essential for real-time automation but challenging to test locally.
• Tunnelmole provides a secure and easy way to give your local n8n instance a public URL.
• The entire process takes just a few minutes to set up.
• Being open-source and self-hostable, Tunnelmole gives you full control and flexibility over your development tools.

By adopting this workflow, you'll accelerate your development cycles, catch bugs earlier, and ultimately build more robust and reliable n8n automations. Happy automating!