DEV Community: Robbie Cahill

I Built a Localhost Tunneling tool in TypeScript - Here's What Surprised Me

Robbie Cahill — Tue, 20 Jan 2026 09:43:15 +0000

For years, I relied on indispensable but proprietary tunneling tools like ngrok. They are fantastic for exposing local development servers to the public internet, making webhook development and cross-device testing a breeze. Yet, the software engineer in me was always curious about the "black box." How did it really work? Could I build an open-source version that was just as simple and effective?

This curiosity led me to create Tunnelmole, a localhost tunneling tool written entirely in TypeScript both on the client and server side. The journey was more challenging and surprising than I anticipated. I dove in expecting to wrestle with network protocols and asynchronous code, which I did. But I also found myself grappling with unexpected challenges, from fighting off phishing scammers to hitting the limitations of modern JavaScript APIs.

This article shares the four most surprising lessons I learned while building a localhost tunnel from scratch. It's a story about technical discovery, unforeseen consequences, and the trade-offs between high-level abstractions and low-level control.

1. The Dark Side: Phishing Scammers Love Tunneling Tools

One of the first "success" metrics for Tunnelmole was, unfortunately, its adoption by malicious actors. Shortly after launching, I noticed a surge in usage that correlated with a spike in abuse reports. Scammers were using Tunnelmole to host phishing sites. They'd set up a fraudulent login page on their local machine, use Tunnelmole to get a public, HTTPS-enabled URL for it, and then use that URL in phishing campaigns.

This presented a significant problem. The service was designed for developers, but its core value proposition a free, anonymous public URL was a magnet for abuse. From the scammer's perspective, it was perfect: they could hide their server's true IP address behind Tunnelmole's infrastructure, making them harder to track down. When their fraudulent tunnelmole.net URL was reported, the abuse complaint would come to my hosting provider, not theirs.

Initially, I played a game of whack-a-mole, manually taking down abusive tunnels as reports came in. But that was never going to be a sustainable approach in the long run. I needed a systemic solution that would make Tunnelmole an unattractive platform for phishers without alienating legitimate developer users.

The solution came in two parts, focused on one goal: deanonymizing the origin of the tunnel.

Solution 1: The `X-Forwarded-For` Header

The first change was to ensure the X-Forwarded-For HTTP header was always present in requests passing through the tunnel. This standard header is used by proxies and load balancers to indicate the IP address of the client that initiated the request.

When a request comes into the Tunnelmole service, the service now adds this header, setting its value to the IP address of the tunnelmole client user.

X-Forwarded-For: <IP address of the Tunnelmole client user>

This means that investigators can easily check this header and find the IP of the server hosting the malicious content.

Solution 2: IP in the URL

The second, more visible change was to embed the client's IP address directly into the randomly generated tunnel URLs. A typical Tunnelmole URL now looks like this:

https://xj38d-ip-111-111-111-111.tunnelmole.net

This makes it abundantly clear, even to a non-technical person, where the content is ultimately being served from. When an abuse report comes in, in addition to taking down the tunnel, I can reply with a simple, clear explanation: "The content is not hosted on our servers. As you can see from the URL, it originates from the IP address 111.111.111.111. Please direct your complaint to the hosting provider for that IP."

These two changes were game-changers. The abuse reports plummeted almost overnight. The scammers realized that Tunnelmole no longer offered them the anonymity they craved. If their origin IP was going to be exposed anyway, they might as well host the phishing site directly on their own server.

This experience also underscored the importance of domain separation. The main website is tunnelmole.com, while the tunnels themselves operate on tunnelmole.net. This was a deliberate choice to protect the reputation and SEO of the main domain. If malicious user generated content hosted on a .tunnelmole.net subdomain caused the entire domain to be blacklisted, it wouldn't take the tunnelmole.com website down with it.

Having malicious content hosted on the main domain, even if I didn't put it there myself, would have serious SEO consequences. Google massively downranks any domains known to have ever had malicious content.

2. Abstraction Disappointment: `fetch` Does Not Give You the Pure HTTP Request

When it came time to write the client-side code that receives a request from the tunnel and forwards it to the user's local server, my first instinct was to reach for a modern, high-level API like fetch. It's the standard for making HTTP requests in browsers and Node.js. This is what i'd used for much of my life for interacting with APIs. My thinking was simple: take the incoming data from the WebSocket, construct a fetch request, and send it to localhost.

I quickly ran into a wall. High-level abstractions like fetch and even axios are designed for convenience, not for perfect, byte-for-byte proxying. They are "opinionated" and manipulate the underlying HTTP request in ways that are helpful for most application development but disastrous for a tunneling tool.

Here were the main problems:

Header Manipulation: fetch automatically lowercases all header names. This is usually fine, as HTTP header names are case-insensitive. However, a true tunnel should be transparent. It shouldn't alter the data passing through it. If a developer is debugging a case-sensitive header issue with a poorly-behaved client, the tunnel shouldn't hide the problem.
Body Parsing: fetch wants to be helpful with the request and response bodies. It tries to parse them, stream them, and handle content encoding. But for a tunnel, the body is just an opaque bag of bytes. It could be a JSON payload, a multipart form upload, or something binary. I needed to grab the raw body as a Buffer and forward it verbatim. Trying to force fetch to "un-process" the body was clumsy and unreliable.
Lack of Low-Level Control: I couldn't get the raw, untouched HTTP request. The tool was always one step removed from the underlying socket.

After struggling with these libraries, I realized I was using the wrong tool for the job. I didn't need a convenient API for making requests; I needed a low-level tool for reconstructing them.

The solution was to go back to basics and use Node.js's built-in http module.

The http.request() method provides the granular control I needed. It allows you to set headers exactly as you receive them, write the request body directly from a Buffer, and manage the connection at a much lower level.

By working with the http module, requests could be treated as generic Buffer objects. This ensured that any type of data JSON, HTML, images, binary files could be proxied faithfully without being accidentally misinterpreted or modified by an overly helpful abstraction layer. The tunnel could finally be the transparent conduit it was meant to be.

The only downside here is it does not come with a nice async/await Promise based workflow, so I had to go back to using callbacks.

3. You Can and Should Send Typed JSON as WebSocket Messages

A tunnel works by establishing a persistent connection between the client (tmole) and the server (tunnelmole.net). I chose WebSockets for this, as they provide a full-duplex communication channel over a single TCP connection, perfect for this kind of proxying.

The fundamental challenge with WebSockets is that they just transmit messages, either as strings or binary data. You are responsible for defining the structure and meaning of those messages. The naive approach would be to just send raw data and use a series of if/then/else statements or complex prefixes to figure out what each message represents. Is this the start of a connection? Is it an HTTP request from the server? An HTTP response from the client? This path leads to brittle, unmaintainable spaghetti code.

Instead, I decided to build a simple, explicit messaging "framework" on top of the WebSocket connection. Every message is a JSON object with a type property. This property dictates the shape of the message's payload and determines which handler function should process it.

On the server, when a message arrives from a client, a simple router looks at the type and dispatches it to the correct handler.

Here is a simplified look at the server-side dispatcher:

// Simplified message dispatcher on the server
websocket.on('message', (text: string) => {
    try {
        const message = JSON.parse(text);

        // A map of message types to handler functions
        const handler = messageHandlers[message.type];

        if (handler) {
            handler(message, websocket);
        } else {
            console.error(`No handler for message type: ${message.type}`);
        }
    } catch (error) {
        console.error('Failed to parse or handle message', error);
    }
});

This approach turns a chaotic stream of data into a structured, event-driven system. We have a dedicated handler for each type of message. For example, when a client first connects, it sends an initialize message, which is processed by the initializeHandler.

The real power of this pattern becomes clear when handling the core tunneling logic. When a public request hits a user's URL (e.g., https://...tunnelmole.net/api/test), the server packages it into a ForwardedRequestMessage and sends it to the client over the WebSocket.

The client receives this message and its forwardedRequest handler fires. This handler is the bridge between the WebSocket world and the localhost world.

Here's a closer look at the client-side handler, which uses the http module we discussed earlier:

// From: src/message-handlers/forwarded-request.ts

import http from 'http';
import { ForwardedRequestMessage } from '../messages';
import { Options } from '../options';
import { HostipWebSocket } from '../websocket-wrapper';

export default async function forwardedRequest(
    forwardedRequestMessage: ForwardedRequestMessage, 
    websocket: HostipWebSocket, 
    options: Options
) {
    const { requestId, url, headers, method, body } = forwardedRequestMessage;

    // 1. Configure the local HTTP request options
    const requestOptions: http.RequestOptions = {
        hostname: 'localhost',
        port: options.port, // The user's local port (e.g., 3000)
        path: url,
        method,
        headers
    };

    // 2. Create and dispatch the request to the local server
    const request = http.request(requestOptions, (response) => {
        let responseBody = Buffer.alloc(0);

        // 3. Collect response data chunks as they stream in
        response.on('data', (chunk: Buffer) => {
            responseBody = Buffer.concat([responseBody, chunk]);
        });

        // 4. When the local response ends, send it back to the server
        response.on('end', () => {
            websocket.sendMessage({
                type: 'forwarded-response',
                requestId,
                statusCode: response.statusCode,
                headers: response.headers,
                // The body is Base64 encoded to safely transmit binary data in JSON
                body: responseBody.toString('base64')
            });
        });
    });

    request.on('error', (error) => {
        console.error(`Error forwarding request to localhost:${options.port}:`, error);
        // Inform the server that the request failed
        websocket.sendMessage({
            type: 'forwarded-response',
            requestId,
            statusCode: 502, // Bad Gateway
            headers: {'content-type': 'text/plain'},
            body: Buffer.from(`Tunnelmole: Error connecting to localhost:${options.port}`).toString('base64')
        });
    });

    // 5. Write the request body if it exists
    if (body) {
        // The body from the server is Base64 encoded
        request.write(Buffer.from(body, 'base64'));
    }

    request.end();
}

This typed, message-driven architecture is clean, self-documenting, and extensible. Adding a new capability to the tunnel is as simple as defining a new message type and writing a handler for it. It completely avoids the ambiguity of an unstructured data stream.

4. Node.js Will Not Hold Your Hand: Memory Leaks Are a Thing

Coming from a PHP background, I was accustomed to a stateless, "share-nothing" architecture. In PHP, every web request starts with a clean slate. Memory and resources are allocated, the script runs, a response is sent, and then everything is torn down. It's exceptionally difficult to create a memory leak that persists between requests unless you go out of your way to remove built in safety limits and misconfigure things.

Node.js is a different beast entirely. It's a stateful, long-running process. This is one of its greatest strengths it's fast and efficient because it doesn't have the overhead of bootstrapping and tearing down on every request. But this power comes with responsibility. Any object you create can potentially live for the entire lifetime of the process. If you forget to clean up, you will have a memory leak.

I learned this the hard way. The Tunnelmole service needs to keep track of every active client connection. I created a simple Proxy class to manage this. Here is an oversimplified version of the initial implementation:

// Oversimplified initial version of the connection manager
export default class Proxy {
    private static instance: Proxy;

    // An array to hold all active WebSocket connections
    connections: Array<Connection> = [];

    public addConnection(hostname: string, websocket: HostipWebSocket, /* ...other params */): void {
        const connection: Connection = {
            hostname,
            websocket,
            // ...other properties
        };

        this.connections.push(connection);
    } 

    // ... other methods like findConnectionByHostname() ...
}

This code works perfectly... for a while. It adds new connections to the connections array as clients connect. But what happens when a client disconnects? Nothing. The Connection object, including its now-defunct WebSocket object, remains in the connections array forever.

The array just grew and grew. With each new connection, the server's memory usage crept up. Eventually, the process would exhaust all available memory and crash. I had created a classic memory leak.

The fix, in hindsight, was obvious. I needed to hook into the WebSocket's close event and explicitly clean up the stale connection object.

First, I added a deleteConnection method to the Proxy class:

// In the Proxy class
public deleteConnection(clientId: string): void {
    this.connections = this.connections.filter(conn => conn.clientId !== clientId);
}

Then, I attached a listener to the close event for every new WebSocket connection:

// When a new WebSocket connection is established...
websocket.on('close', (code: number, reason: string) => {
    // Ensure the connection is fully terminated
    websocket.terminate();

    // Use the proxy to remove the connection from the active list
    proxy.deleteConnection(websocket.tunnelmoleClientId);

    console.log(`Connection ${websocket.tunnelmoleClientId} closed.`);
});

With this change in place, the memory leak vanished. The server's memory usage became stable, rising and falling naturally with the number of active users. This experience was a stark reminder that in a long-running environment like Node.js, you are the custodian of memory. You must be diligent about resource cleanup.

Conclusion

Building Tunnelmole from the ground up was an incredible learning experience that went far beyond writing network code. It forced me to confront the real-world operational challenges of running a public service, appreciate the trade-offs between different levels of API abstraction, and internalize the discipline required for state management in a long-running process.

The key takeaways were:

Security Through Transparency: When building public tools, preventing abuse is as important as the core functionality. Sometimes, the best security measure is to remove the veil of anonymity that attracts bad actors.
Use the Right Level of Abstraction: High-level APIs like fetch are powerful but have their limits. For tasks that require absolute control, like proxying, don't be afraid to drop down to lower-level APIs like Node's http module.
Structure Your Data Streams: Don't treat WebSockets as an unstructured pipe. A simple, typed messaging protocol brings order to chaos and makes your application robust and extensible.
Manage Your State Diligently: In stateful environments like Node.js, you are responsible for memory management. Always have a plan for cleaning up objects and resources that are no longer needed.

I set out to build an open-source alternative to proprietary software and in the process, I learned quite a lot about NodeJS and the core of the HTTP protocol. If you're a developer who loves to peek inside the black box, I can't recommend a project like this enough.

If you're interested in checking out the result of this journey, you can try Tunnelmole now or dive into the full, non oversimplfied code on GitHub. It’s open source, and contributions are always welcome.

AI Agents Deleting Home Folders? Run Your Agent in Firejail and Stay Safe

Robbie Cahill — Mon, 15 Dec 2025 09:58:37 +0000

Introduction: The Double-Edged Sword of AI Agents

As a developer, I'm always looking for tools that boost productivity. While building Tunnelmole, an open-source tunneling tool and a popular alternative to ngrok, I've increasingly used AI agents for various coding and business-related tasks. When used correctly and with human oversight, these agents are incredibly powerful. However, giving them unrestricted access to your development machine is like handing over your password to an unpredictable intern - powerful, but potentially catastrophic. If something disastrous happens, in the same way you can't blame an unpredictable over eager intern who was given too much access, you can't really blame the AI agent. Its on you to set up a secure environment for the agent to run in.

The convenience of letting an agent read files, run commands, and write code directly on your machine is undeniable. But this convenience comes with a massive, often overlooked, risk. What happens when the AI misunderstands a prompt? Or worse, what if a bug in the agent's logic causes it to execute a destructive command?

This isn't a theoretical problem. A recent post on Reddit sent a chill down the spine of every developer using AI tools. A user on reddit reported that the Claude CLI deleted their entire home directory, effectively wiping their Mac.

The culprit was a single, terrifying command generated by the AI:

rm -rf tests/ patches/ plan/ ~/

Most of that command is harmless, targeting project-specific directories. The disaster lies in the final two characters: ~/. In Unix-like systems, ~ is a shortcut for the current user's home directory. The command, therefore, translates to "forcefully and recursively delete the 'tests' directory, the 'patches' directory, the 'plan' directory, AND MY ENTIRE HOME FOLDER." Everything: documents, photos, dotfiles, and years of work, all gone in an instant.

This incident is a stark warning. We must build guardrails. The solution is sandboxing: running the AI agent in a restricted, controlled environment where its capabilities are strictly limited.

In this guide, I'll show you how to use a powerful tool called Firejail to create a secure sandbox for your VS Code-based AI agent. I personally use Kilo Code, but these instructions are directly applicable to other popular agents like GitHub Copilot and can be easily adapted for agentic IDEs such as Windsurf, or any other tool that runs within VS Code.

Firejail uses Linux kernel features such as namespaces to work, so this guide will only work on Linux, either running on your host machine or inside a VM. It may or may not work on Windows Subsystem for Linux with GUI apps like vscode.

What is Firejail and Why is it Effective?

Firejail is a SUID (Set owner User ID upon execution) security sandbox program for Linux. In simpler terms, it's a utility that allows you to run any application in a tightly controlled environment. It uses security features built directly into the Linux kernel, such as namespaces and seccomp-bpf, to isolate the application from your system.

Here’s why this approach is so effective:

Kernel-Level Enforcement: The restrictions are not just suggestions; they are enforced by the operating system's kernel. If the sandboxed application (like VS Code and the AI agent inside it) tries to access a file or execute a command it's not allowed to, the kernel will block the attempt. It doesn't matter how clever the application is; it simply doesn't have the permission.
Default-Deny Philosophy: A well-configured sandbox works on a "default-deny" basis. Instead of trying to list everything an application can't do, you define the very small set of things it can do. Everything else is forbidden by default. This is vastly more secure than a blacklist approach.
Lightweight and Transparent: Firejail is not a virtual machine. It's a lightweight wrapper that imposes minimal performance overhead. Once configured, you launch your application with a simple firejail <app> command, and it runs inside its secure bubble transparently.

You can typically install Firejail from your distribution's package manager. For example, on Debian or Ubuntu:

sudo apt-get update && sudo apt-get install firejail

Crafting a Secure Firejail Profile for VS Code

Out of the box, Firejail comes with default profiles for many common applications, including code (VS Code). However, to protect ourselves from the specific risk of home directory deletion, we need to create a custom, more restrictive profile. Our goal is to prevent VS Code and any extensions from accessing anything outside of our designated project folders.

First, create the directory for custom Firejail profiles if it doesn't exist:

mkdir -p ~/.config/firejail

Next, create a new profile file for VS Code:

touch ~/.config/firejail/code.profile

Now, open ~/.config/firejail/code.profile in your favorite text editor and paste in the following configuration.

In this example, all of my coding projects are in the $HOME/projects folder, so this is included. You'll need to change this to point to where you keep your projects. If you keep code in multiple places you can add multiple folders by copying and pasting the whole line, then editing the path.

# Firejail profile for Visual Studio Code
# This profile is designed to be highly restrictive for running AI agents safely.

# Persistent local customizations
include code.local

# Persistent global definitions
include globals.local

# These are disabled for a more restrictive environment.
ignore include disable-devel.inc
ignore include disable-exec.inc
ignore include disable-interpreters.inc
ignore include disable-xdg.inc
ignore whitelist ${DOWNLOADS}
ignore whitelist ${HOME}/.config/Electron
ignore whitelist ${HOME}/.config/electron*-flag*.conf
ignore include whitelist-common.inc
ignore include whitelist-runuser-common.inc
ignore include whitelist-usr-share-common.inc
ignore include whitelist-var-common.inc
ignore apparmor
ignore disable-mnt

# Block access to D-Bus to prevent inter-process communication
ignore dbus-user none
ignore dbus-system none

# Allows files commonly used by IDEs, but we will override with a strict whitelist.
include allow-common-devel.inc

# --- WHITELISTING ---
# This is the core of our security model. By using 'whitelist', we deny
# everything by default and only allow access to the paths specified below.

# Allow read-write access ONLY to VS Code's own configuration directories
whitelist ${HOME}/.config/Code
whitelist ${HOME}/.config/Code - OSS
whitelist ${HOME}/.vscode
whitelist ${HOME}/.vscode-oss

# IMPORTANT: Change this to point to where you keep your coding projects! You can add multiple folders here if needed.
whitelist ${HOME}/projects

# Allow access to shell configuration for the integrated terminal to work properly.
whitelist ${HOME}/.zshrc
whitelist ${HOME}/.bashrc
whitelist ${HOME}/.oh-my-zsh
whitelist ${HOME}/.profile

# Create the Code config directory structure if it doesn't exist. VSCode crashes silently without these lines
mkdir ${HOME}/.config/Code
mkdir ${HOME}/.config/Code/logs

# Security hardening: disable sound and prevent execution of files in /tmp
nosound
noexec /tmp

# Redirect to the common Electron profile for other basic settings
include electron-common.profile

Deconstructing the Security Profile

This profile might look complex, but its strategy is simple and built around the whitelist directive. Let's break down the most important parts:

ignore dbus-user none and ignore dbus-system none: These lines are crucial for isolation. They prevent the sandboxed application from communicating with other processes running on your machine via D-Bus, a common inter-process communication system.
The whitelist Directives: This is the heart of our defense. When Firejail sees whitelist, it immediately blocks access to the entire filesystem. It then selectively re-enables access only for the paths that follow.
whitelist ${HOME}/.config/Code: Allows VS Code to read and write its own configuration, which is necessary for it to function.
whitelist ${HOME}/projects: This is the most important line for our security. It tells Firejail that VS Code is allowed to access the ~/projects directory and nothing else in your home folder. This is where you should clone your repositories and work on your code. The AI agent, running inside this sandbox, will only be able to see and modify files within this directory.
whitelist ${HOME}/.bashrc (and other dotfiles): These are included so that the integrated terminal in VS Code loads your shell configuration and works as you expect.
noexec /tmp: This is a hardening measure that prevents any file in the /tmp directory from being executed, a common attack vector.

With this profile in place, even if an AI agent tries to run rm -rf ~/, the kernel will deny it access to ~, but it would succeed if it tried to run rm -rf ~/projects/some-repo (which is the intended behavior).

You should still regularly back up the folder(s) where you have your coding projects, since the AI agent still has full access to these.

Testing Your Sandbox: Trust, But Verify

Implementing security measures is only half the battle. You must test them to ensure they work as expected. Let's verify that our sandbox correctly protects the home directory.

Step 1: Create a "Canary" File

First, we'll create a test file in your home directory. This file sits outside our whitelisted ~/projects folder and will act as our canary in the coal mine.

Open a terminal and run:

echo "This file should not be accessible" > ~/test

Step 2: Launch VS Code Inside Firejail

Close any running instances of VS Code. Then, launch it from your terminal using the firejail command:

firejail code

Firejail will automatically detect and apply our custom ~/.config/firejail/code.profile. Your VS Code window will open, but it is now running inside the secure sandbox.

Step 3: Instruct the AI Agent to Breach the Walls

Now for the real test. Open your VS Code-based AI agent (Kilo Code, Copilot, etc.) that has access to a terminal or can execute shell commands. Give it the following prompt:

You are running in a Firejail sandbox and I'd like you to help me test its security. Please try to read the file located at `~/test` using the `cat` command and show me its contents.

Step 4: Analyze the (Successful) Failure

If your sandbox is configured correctly, the AI agent will fail. The kernel will block the cat command's attempt to access the file, and the agent's response should reflect this. You should see something similar to this:

The agent reports cat: /home/user/do_not_touch.txt: Permission denied. This "Permission denied" message is the sweet sound of success. It is definitive proof that our sandbox is working. The AI-driven tool, despite being instructed to, was powerless to escape its designated ~/projects directory.

Conclusion: Develop Powerfully, and Safely

AI agents are transformative tools for software development, but their power demands a new level of caution. As the "Claude-pocalypse" incident on Reddit demonstrates, running them in an unrestricted environment is an unacceptable risk.

By using Firejail to sandbox your development tools, you can harness the productivity of AI without gambling with your data. The setup is straightforward:

Install Firejail.
Create a strict, whitelist-based profile that limits access to a single ~/projects directory.
Launch your editor via firejail code.
Always test your configuration to ensure it's secure.

This small investment in setting up a sandboxed environment provides robust, kernel-enforced peace of mind. You can let your AI agent write code, refactor, and automate tasks, confident that even in the worst-case scenario, the blast radius is contained, and your home directory remains safe.

Happy and secure coding!

6 Ways A Node Developer Can Drastically Boost Their Productivity in 2025

Robbie Cahill — Mon, 10 Nov 2025 08:46:14 +0000

Introduction

As a Node.js developer, finding efficient ways to write high-quality code is an ongoing part of the craft. There are only so many hours in a day that you can dedicate to coding. The landscape of tools and best practices is constantly evolving, and staying productive means keeping your workflow sharp and efficient. These six productivity tips will supercharge your development process, saving you hours of valuable time that you can reinvest in building better applications, learning new skills, or simply enjoying other activities.

This is not an exhaustive list, but mastering these techniques will give you a significant edge. It took me years to discover and internalize all of them, but you can learn them all in a single afternoon. Whether you're a junior developer or a seasoned engineer, integrating these practices will drastically improve your productivity.

Many Senior or higher level devs are already doing many of the techniques below. But they're worth learning at any stage and even a beginner can pick them up easily.

1. Master the Fuzzy Finder in Your IDE

In modern software development, we often work with large, complex codebases, sometimes containing thousands of files. How do you quickly locate a specific file like employee.js, buried deep within a directory structure such as /src/features/authentication/userTypes/employee.js hidden amongst thousands of other files? Manually navigating the directory tree is slow and inefficient, and interrupting a colleague for directions isn't always the best approach.

The solution is the fuzzy finder, a powerful IDE feature that lets you find files quickly.

In VS Code, simply press Ctrl+P (or Cmd+P on Mac) and start typing the name of the file you're looking for. The results appear as you type, intelligently matching your query even if you only type parts of the filename or path.

If you're using a JetBrains IDE like WebStorm or IntelliJ IDEA, press Shift twice quickly (Double Shift) to bring up a similar "Search Everywhere" dialog, which can find files, classes, symbols, and more.

Adopting the fuzzy finder is a small change that yields massive time savings, eliminating minutes of fruitless searching every single day.

2. Use a Real Debugger Instead of `console.log()`

One of the most significant leaps in my journey as a developer was learning to use a real debugger. It transformed my ability to fix bugs and build complex features, often turning a day's worth of work into a couple of hours. Debugging is especially invaluable when you're navigating an unfamiliar codebase. You can trace complex logic, inspect the state of your application at any point, and understand convoluted code without having to guess.

If you've ever found yourself littering your code with console.log() statements, you know how tedious it can be. You print one value, then another, adding more and more statements until your console is a mess. It's like trying to find your way in the dark with a tiny flashlight. Your working memory can only hold so much information, and soon you're scrolling back and forth, trying to piece the puzzle together.

Enter the debugger. By setting a "breakpoint" in your code and running your application in debug mode, the program execution will pause at that exact line. From there, your IDE will show you all the variables in the current scope, the call stack, and more.

With a single breakpoint, you get a complete snapshot of your application's state, eliminating the need to juggle multiple console.log() outputs mentally. Debuggers can do more - pressing "Step Over" a few or more times runs your code line by line. "Step Into" steps into a function call, letting you trace the execution of your code seamlessly.

As you become more advanced, you can even debug the internal code of frameworks like Express. This unlocks a deeper level of understanding that documentation alone can't provide. To get started with setting up the debugger in VS Code for a Node.js application, check the official documentation or one of the many excellent guides available online.

3. Embrace `async/await` and Banish "Callback Hell"

Node.js is built around asynchronous operations, which can be tricky to manage. In the early days, this led to a pattern infamously known as "Callback Hell" or the "Pyramid of Doom."

Consider this pre-async/await example:

// The old way: Callback Hell
function addFavoriteProduct(userId, favoriteProduct) {
    userRepository.get(userId, (err, user) => {
        if (err) {
            // Handle error
            return;
        }
        profileRepository.get(user.profileId, (err, userProfile) => {
            if (err) {
                // Handle error
                return;
            }
            productsRepository.getFavoriteProducts(userProfile.favoriteProductsId, (err, favoriteProducts) => {
                if (err) {
                    // Handle error
                    return;
                }
                favoriteProducts.add(favoriteProduct);
            });
        });
    });
}

This code is deeply nested, difficult to read, and prone to errors. Each new asynchronous step adds another layer of indentation, making the control flow hard to follow.

Fortunately, modern JavaScript (since Node.js v8) offers a much cleaner syntax: async/await.

// The modern way: async/await
async function addFavoriteProduct(userId, favoriteProduct) {
    try {
        const user = await userRepository.get(userId);
        const userProfile = await profileRepository.get(user.profileId);
        const favoriteProducts = await productsRepository.getFavoriteProducts(userProfile.favoriteProductsId);
        await favoriteProducts.add(favoriteProduct);
    } catch (error) {
        // Handle all errors in one place
        console.error("Failed to add favorite product:", error);
    }
}

This revised code is flat, linear, and reads almost like synchronous code. It's vastly easier to understand, maintain, and debug. If you encounter older tutorials or codebases using the callback pattern, make it a priority to refactor them to use async/await.

4. Share Your Work Quickly with a Public URL

Did you know you can get a public, shareable URL for a Node.js application running on localhost? Even if you're behind a corporate firewall or a complex network, you can expose your local server to the internet in seconds with an open-source tunneling tool like Tunnelmole.

This capability is a game-changer for collaboration. You can:

Get fast feedback: Share your work-in-progress with product managers, designers, or clients without a full deployment.
Debug live integrations: Test webhooks from services like Stripe, Slack, or Shopify by giving them a real HTTPS endpoint that tunnels to your machine.
Collaborate with frontend developers: Provide a live backend API for them to build against.
Test on real devices: Easily access your local web app from your phone or other devices to test your site on mobile.

Tunnelmole is a free and open-source tool that makes this incredibly simple.

First, install Tunnelmole. If you have Node.js installed, the easiest way is with npm:

sudo npm install -g tunnelmole

Alternatively, you can use the one-line installer for Linux, Mac, or WSL:

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

Once installed, if your local Node.js app is running on port 3000, just run:

tmole 3000

Tunnelmole will give you a unique public URL that forwards all traffic to your local server.

$ tmole 3000
Your Tunnelmole Public URLs are below and are accessible internet wide.

https://cqcu2t-ip-49-185-26-79.tunnelmole.net ⟶ http://localhost:3000
http://cqcu2t-ip-49-185-26-79.tunnelmole.net ⟶ http://localhost:3000

Now you can share this URL with anyone, anywhere. For more advanced use cases, like custom subdomains, you can check out the Tunnelmole documentation.

5. Automate Repetitive Tasks with `npm` Scripts

Every project has a set of routine tasks: compiling code, running tests, linting files, starting the server, etc. Instead of manually typing these commands and remembering all their flags, you can automate them using npm scripts in your package.json file.

{
  "name": "my-awesome-app",
  "version": "1.0.0",
  "main": "dist/app.js",
  "scripts": {
    "build": "tsc -p ./",
    "watch": "tsc -p ./ -w",
    "test": "jest --watch",
    "lint": "eslint . --ext .ts",
    "start": "node dist/app.js",
    "dev": "nodemon src/app.ts"
  },
  "dependencies": {
    "express": "^4.17.1"
  },
  "devDependencies": {
    "typescript": "^4.5.0",
    "jest": "^27.4.0",
    "eslint": "^8.3.0",
    "nodemon": "^2.0.15",
    "ts-node": "^10.4.0"
  }
}

In this example (for a TypeScript project):

npm run build compiles the TypeScript code into JavaScript.
npm run watch does the same but watches for changes and recompiles automatically.
npm test runs the Jest test suite.
npm run lint checks the code for style and syntax errors with ESLint.
npm start runs the compiled application.
npm run dev uses nodemon to run the app in development mode with auto-restarts.

By defining these scripts, you create a consistent, single-command workflow for yourself and anyone else who works on the project. start and test are special scripts that can be run without the run keyword (i.e., npm start, npm test).

6. Get Fast Feedback with `nodemon`

When you make a change to your code while the server is running with node app.js, you have to manually stop it (Ctrl+C) and then restart it to see the effects. This cycle might only take five seconds, but if you do it hundreds of times a day, those seconds add up to hours of wasted time over a week.

nodemon solves this problem elegantly. It's a utility that wraps your Node application and automatically restarts it whenever it detects file changes in the directory.

First, install it globally or as a dev dependency:

npm install -g nodemon

npm install --save-dev nodemon

Then, instead of node app.js, you run:

nodemon app.js

Now, every time you save a file, nodemon will automatically restart your server, creating a seamless and rapid feedback loop.

$ nodemon src/app.ts
[nodemon] 2.0.15
[nodemon] to restart at any time, enter `rs`
[nodemon] watching path(s): *.*
[nodemon] watching extensions: ts,json
[nodemon] starting `ts-node src/app.ts`
Server listening on http://localhost:3000

# (I save a file here)

[nodemon] restarting due to changes...
[nodemon] starting `ts-node src/app.ts`
Server listening on http://localhost:3000

Pro-tip: Integrate nodemon into your dev script in package.json as shown in the previous section for a powerful development workflow.

Conclusion

Productivity isn't about working harder; it's about working smarter. By incorporating these six techniques—the fuzzy finder, a real debugger, async/await, tunnelmole, npm scripts, and nodemon—into your daily Node.js development practice, you can eliminate friction, reduce cognitive load, and save a significant amount of time.

These simple adjustments can have a profound impact on your efficiency and job satisfaction. If you found this article useful, please consider sharing it with your colleagues and on social media to help others boost their productivity too.

Happy Coding!

Airtable Webhook Integration: A Developer's Guide

Robbie Cahill — Mon, 01 Sep 2025 08:00:29 +0000

Introduction

Airtable has revolutionized how teams manage data, blending the simplicity of a spreadsheet with the power of a database. But its true potential is unlocked when you connect it to other services. One of the most powerful ways to do this is through Airtable webhooks, allowing you to send data to external applications in real-time whenever a change occurs in your base.

However, developing and testing these webhooks presents a common challenge: Airtable needs to send data to a public URL, but your development environment runs on localhost, which is inaccessible from the public internet.

This guide solves that problem. We'll walk you through the entire process of setting up a local Node.js and Express application to receive Airtable webhooks. You'll learn how to use Tunnelmole, a free and open-source tool, to give your local server a public URL, enabling you to build and debug your Airtable integrations with ease.

What are Airtable Webhooks?

In a nutshell, a webhook is an automated message sent from one app to another when a specific event happens. It's a "push" model, which is far more efficient than the traditional "pull" or API polling model where your application would have to repeatedly ask Airtable if there is any new data.

In Airtable, webhooks are implemented through the Airtable Automations feature. You can configure an Automation to trigger on various events, such as:

When a new record is created.
When a record is updated.
When a record enters a specific view.
When a record matches certain conditions.

When the trigger event occurs, your Automation can perform an action. One of the most versatile actions is "Send webhook," which sends an HTTP request with a data payload to a URL you specify. This is the mechanism we'll use to connect Airtable to our local development environment.

Why You Need a Public URL for Local Development

When an Airtable Automation triggers a webhook, its servers—located on the public internet—send an HTTP request. For that request to reach your application, your application must also be accessible from the public internet.

Your local development server, typically running at an address like http://localhost:3000, is only visible on your own computer. It is entirely unreachable by Airtable's servers.

This is where a tunneling tool becomes essential. We will use Tunnelmole to create a secure tunnel from a publicly accessible URL directly to your local server. When Airtable sends a webhook to this public URL, Tunnelmole forwards it to your localhost, allowing you to receive real-time data without deploying your code or configuring complex network settings.

Setting Up Your Local Webhook Receiver (Node.js & Express)

First, let's build a simple web server to act as our webhook receiver. We'll use Node.js and the popular Express framework.

Prerequisites

Node.js and npm installed on your system.
A text editor like VS Code.

Step 1: Initialize Your Project

Create a new folder for your project, navigate into it, and initialize a new Node.js project.

mkdir airtable-webhook-receiver
cd airtable-webhook-receiver
npm init -y

Step 2: Install Express

Next, install the Express framework.

npm install express

Step 3: Create the Server Code

Create a file named app.js and add the following code. This code sets up a simple Express server with a single endpoint, /airtable-webhook, which will listen for POST requests from Airtable.

const express = require('express');
const app = express();
const port = 3000;

// Use the built-in Express middleware to parse JSON bodies
app.use(express.json());

app.post('/airtable-webhook', (request, response) => {
    console.log('🎉 Airtable Webhook Received!');

    // The webhook data from Airtable is in request.body
    const { body } = request;
    console.log('Webhook Body:', JSON.stringify(body, null, 2));

    // You can now process the data
    // For example, get the triggering record's ID
    const recordId = body.recordId;
    if (recordId) {
        console.log(`Processing data for record: ${recordId}`);
    }

    // Send a 200 OK response to Airtable to acknowledge receipt
    response.status(200).send('Webhook received successfully.');
});

app.listen(port, () => {
    console.log(`Webhook receiver listening at http://localhost:${port}`);
});

Step 4: Run Your Server

Start your server from the terminal:

node app.js

You should see the message: Webhook receiver listening at http://localhost:3000. Your local endpoint is now ready at http://localhost:3000/airtable-webhook.

Exposing Your Local Server with Tunnelmole

Now, let's get a public URL for your local server.

Install Tunnelmole

If you have NodeJS installed, the easiest way to install Tunnelmole is with npm.

sudo npm install -g tunnelmole

Alternatively, you can use curl on Linux or macOS:

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

For Windows, you can download the executable and add it to your PATH. Detailed instructions are on the Tunnelmole website.

Run Tunnelmole

With your Node.js server running, open a new terminal window and run the following command to tunnel port 3000:

tmole 3000

Tunnelmole will start and display your public URLs.

$ tmole 3000
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:3000
http://cqcu2t-ip-49-185-26-79.tunnelmole.net ⟶ http://localhost:3000

Copy the HTTPS URL (e.g., https://cqcu2t-ip-49-185-26-79.tunnelmole.net). This is the public address for your local server. Our full webhook URL will be this address plus our endpoint: https://<your-tunnelmole-url>/airtable-webhook.

How Tunnelmole Works

The concept behind Tunnelmole is straightforward but powerful. The Tunnelmole client on your machine establishes a persistent, secure connection to the Tunnelmole service in the cloud. The service generates a unique public URL that points to this connection. When an external service like Airtable sends a request to your public URL, the Tunnelmole service forwards that request through the secure tunnel to the client on your machine, which then passes it to your local server on localhost.

One of the key benefits of Tunnelmole is that it's fully open source. Both the client and the server code are available for review. For maximum privacy and control, you can even self-host the Tunnelmole service on your own server.

Configuring the Airtable Automation

Now we're ready to set up the automation in Airtable.

Open Your Airtable Base: Navigate to the base and table you want to use for the trigger.
Create an Automation: Click "Automations" in the top-left corner, then click the "+ New automation" button.
Choose a Trigger: Select a trigger. For this example, let's use "When a record is created". Configure it to watch the table you've chosen. Run a test to ensure it's configured correctly.
Add an Action: Click "+ Add action" and select "Send webhook".
Configure the Webhook:
- URL: Paste your full Tunnelmole webhook URL here (e.g., https://<your-tunnelmole-url>/airtable-webhook).
- Body: Airtable lets you build a custom JSON payload. Switch to the "JSON" format. You can insert dynamic values from the triggering record. Let's create a simple payload that includes the record's ID and the value of a field named "Name".
```
{
  "recordId": "{recordId}",
  "name": "{Name}",
  "message": "A new record was created in Airtable!"
}
```
Click the blue "+" icon to insert dynamic field values from your table.
Test and Enable:
- Click "Test action" to send a sample webhook.
- Check your local server's terminal. You should see the webhook data printed to the console!
- Once you confirm it's working, toggle the "Active" switch at the top of the automation to turn it on.

Testing End-to-End

With everything set up, let's perform a final, live test:

Go to your Airtable table.
Create a new record.
Next, check the terminal window where your app.js server is running.

You should see the console log output, confirming that Airtable successfully sent a webhook to Tunnelmole, which forwarded it to your local application.

🎉 Airtable Webhook Received!
Webhook Body: {
  "recordId": "recXXXXXXXXXXXXXX",
  "name": "My New Test Record",
  "message": "A new record was created in Airtable!"
}
Processing data for record: recXXXXXXXXXXXXXX

Securing Your Webhook

Your Tunnelmole URL is public, which means anyone who knows the URL could potentially send requests to it. For a production application, you should always secure your webhook endpoint.

Airtable supports sending a secret in the webhook headers.

In Airtable: In the webhook action configuration, go to the "Headers" section. Add a new header:
- Key: Authorization
- Value: Bearer YOUR_SUPER_SECRET_TOKEN (replace this with a long, random string).
In Your Node.js App: Update your app.js to check for this header before processing the request.

const express = require('express');
const app = express();
const port = 3000;

// This should be stored securely, e.g., in an environment variable
const WEBHOOK_SECRET = 'YOUR_SUPER_SECRET_TOKEN';

app.use(express.json());

app.post('/airtable-webhook', (request, response) => {
    // 1. Verify the secret token
    const authHeader = request.headers['authorization'];
    const token = authHeader && authHeader.split(' ')[1];

    if (token !== WEBHOOK_SECRET) {
        console.warn('⚠️ Unauthorized webhook attempt blocked.');
        return response.status(403).send('Forbidden: Invalid signature.');
    }

    // 2. Process the webhook if authorized
    console.log('🎉 Airtable Webhook Received (Authorized)!');
    const { body } = request;
    console.log('Webhook Body:', JSON.stringify(body, null, 2));

    response.status(200).send('Webhook received successfully.');
});

app.listen(port, () => {
    console.log(`Webhook receiver listening at http://localhost:${port}`);
});

Now, only requests containing the correct secret token will be processed, making your local endpoint secure.

Conclusion

You've now mastered the workflow for developing Airtable webhooks locally. By creating a simple Express server and using Tunnelmole to expose it to the internet, you can build, test, and debug your integrations in a fast, efficient feedback loop without ever leaving your local machine.

You've learned to:

Build a Node.js server to receive webhooks.
Use Tunnelmole to create a public URL for your local server.
Configure an Airtable Automation to send webhook data.
Secure your webhook endpoint with a secret token.

This powerful combination enables you to build robust, real-time integrations between Airtable and any other service you can imagine.

Tunnelmole Features

Open Source: Review the code and contribute on GitHub.
Free Public URLs: Get started immediately with randomly generated URLs.
Custom Subdomains: Use a stable, predictable URL for your projects (paid or self-hosted).
Self-Hostable: For maximum control and privacy, you can host the Tunnelmole service on your own infrastructure.
Native NodeJS Application: Built with a modern, fast, and widely-used technology stack.

How to Use Google Chat Webhooks: A Complete Guide

Robbie Cahill — Mon, 01 Sep 2025 08:00:06 +0000

Google Chat has become a central hub for team communication, and its real power for developers is unlocked through webhooks. Webhooks allow you to integrate external services, build custom bots, and automate workflows directly within your chat spaces. This guide will walk you through everything you need to know about using Google Chat webhooks, from sending simple notifications to building interactive bots that can respond to user commands.

We'll cover two primary use cases:

Incoming Webhooks: Sending messages from your applications into a Google Chat space. This is perfect for notifications, alerts, and reporting.
Outgoing Webhooks (Interactive Apps): Receiving messages from Google Chat in your application. This allows you to build bots that respond to slash commands and user interactions.

We'll use Tunnelmole, a free and open source tunneling tool, to get a public HTTPS url pointing to your localhost within seconds that you can use to receive the webhook requests.

By the end of this guide, you'll be able to create sophisticated integrations that make your team more productive and your systems more connected.

Part 1: Incoming Webhooks - Pushing Messages to Google Chat

Incoming webhooks provide a simple way to post messages from your applications into Google Chat. Each incoming webhook you create generates a unique URL. When your application sends an HTTP POST request with a JSON payload to this URL, the message appears in the designated chat space.

This is incredibly useful for:

CI/CD Notifications: Announcing successful builds, deployments, or test failures from Jenkins, GitHub Actions, or GitLab.
System Alerts: Notifying the team about server errors, high CPU usage, or application exceptions from monitoring tools like Prometheus or Grafana.
Business Updates: Posting new customer sign-ups, sales leads from your CRM, or support ticket updates.

Creating an Incoming Webhook in Google Chat

First, you need to create a webhook URL within the Google Chat space where you want to post messages.

Open Google Chat and go to the space (or channel) where you want to add the webhook.
Click on the space name at the top, and from the dropdown menu, select Apps & Integrations.
Click "Add webhooks".
Give your webhook a descriptive name (e.g., "Build Server Notifications") and optionally, an avatar URL for the bot.
Click "Save".
Google Chat will generate a unique URL for your webhook. Copy this URL and keep it safe. This URL is a secret; anyone with it can post messages to your space.

Sending Your First Message with `curl`

The simplest way to test your new webhook is by using curl from your terminal. Let's send a basic text message.

Replace YOUR_WEBHOOK_URL with the URL you copied in the previous step.

curl \
   -X POST \
   -H 'Content-Type: application/json' \
   'YOUR_WEBHOOK_URL' \
   -d '{"text": "Hello from my first webhook!"}'

If successful, you'll see the message "Hello from my first webhook!" appear within a few seconds in your Google Chat space, posted by the webhook app you just configured.

Crafting Rich Messages with Cards

While simple text messages are useful, Google Chat's real power comes from "Cards V2". Cards are UI elements that can display information with rich formatting, images, buttons, and other interactive components.

Let's send a more complex card message that includes a header, some text widgets, and a button.

curl \
   -X POST \
   -H 'Content-Type: application/json' \
   'YOUR_WEBHOOK_URL' \
   -d '{
     "cardsV2": [
       {
         "cardId": "unique-card-id",
         "card": {
           "header": {
             "title": "New Build Notification",
             "subtitle": "Project: AwesomeApp",
             "imageUrl": "https://www.gstatic.com/images/icons/material/system_gm/1x/build_white_24dp.png",
             "imageType": "CIRCLE"
           },
           "sections": [
             {
               "header": "Build Successful",
               "collapsible": true,
               "widgets": [
                 {
                   "decoratedText": {
                     "topLabel": "Commit SHA",
                     "text": "a1b2c3d4"
                   }
                 },
                 {
                   "decoratedText": {
                     "topLabel": "Branch",
                     "text": "main"
                   }
                 },
                 {
                   "buttonList": {
                     "buttons": [
                       {
                         "text": "View Build Logs",
                         "onClick": {
                           "openLink": {
                             "url": "https://example.com/build/123"
                           }
                         }
                       }
                     ]
                   }
                 }
               ]
             }
           ]
         }
       }
     ]
   }'

This JSON payload is more complex, but it creates a much richer notification in your chat space, complete with a title, icon, structured information, and a clickable button that links to the build logs.

Example: Sending a Google Chat Message with Node.js

In a real-world application, you'll be sending these requests programmatically. Here's how you can send a card message using Node.js with the built-in https module.

const https = require('https');

function sendGoogleChatMessage(webhookUrl, cardPayload) {
  const data = JSON.stringify(cardPayload);

  const url = new URL(webhookUrl);

  const options = {
    hostname: url.hostname,
    port: 443,
    path: url.pathname + url.search,
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Content-Length': data.length,
    },
  };

  const req = https.request(options, (res) => {
    console.log(`statusCode: ${res.statusCode}`);
    res.on('data', (d) => {
      process.stdout.write(d);
    });
  });

  req.on('error', (error) => {
    console.error(error);
  });

  req.write(data);
  req.end();
}

// --- Usage ---
const WEBHOOK_URL = 'YOUR_WEBHOOK_URL'; // Replace with your actual webhook URL

const buildSuccessCard = {
  cardsV2: [
    {
      cardId: "build-success-card",
      card: {
        header: {
          title: "Build Succeeded",
          subtitle: "Project: Web-Frontend",
          imageUrl: "https://www.gstatic.com/images/icons/material/system_gm/1x/task_alt_white_24dp.png",
          imageType: "CIRCLE"
        },
        sections: [
          {
            widgets: [
              { decoratedText: { topLabel: "Branch", text: "features/new-login" } },
              { decoratedText: { topLabel: "Deployed To", text: "Staging Environment" } },
              {
                buttonList: {
                  buttons: [
                    {
                      text: "Visit Staging Site",
                      onClick: { openLink: { url: "https://staging.example.com" } }
                    }
                  ]
                }
              }
            ]
          }
        ]
      }
    }
  ]
};

sendGoogleChatMessage(WEBHOOK_URL, buildSuccessCard);

Save this as sendNotification.js, replace the placeholder URL, and run it with node sendNotification.js. Your formatted card will be posted to the chat space.

Part 2: Outgoing Webhooks - Building Interactive Chat Apps

While incoming webhooks are for one-way communication, the real magic happens when your application can receive events from Google Chat and respond. This is how you build interactive bots, slash commands, and other powerful integrations.

Use cases include:

Slash Commands: Typing /deploy production to trigger a deployment pipeline.
Interactive Cards: Clicking a button on a card to approve a request or update a task's status.
Chat Bots: Mentioning a bot to ask for information, like @JiraBot find TICKET-123.

To do this, Google Chat needs to send an HTTP POST request to your application. This means your application must be running on a publicly accessible URL.

The Challenge: Developing Locally

When you're developing a chat app, you're typically running your code on your local machine (http://localhost:3000, for example). This server is not reachable from the public internet, so Google's servers can't send webhook events to it.

You could deploy your code to a cloud server every time you make a change, but this is slow, tedious, and makes debugging nearly impossible. You need a way to expose your local development server to the internet.

The Solution: Tunnelmole for a Public URL

This is where Tunnelmole comes in. Tunnelmole is a free and open-source tool that creates a secure tunnel from a public URL to your local server. It gives you a temporary, public HTTPS URL that forwards all requests to your localhost port.

This allows you to receive webhooks from Google Chat directly on your development machine, making it incredibly easy to build and test your interactive apps in real-time.

Here's a high-level look at how it works:

Tunnelmole is a native NodeJS application, and its key features include:

Open Source: The client and server are fully open source, giving you complete transparency and control.
Self-Hostable: While Tunnelmole offers a convenient hosted service, you have the option to host the tunnel server yourself for maximum privacy and control.
Easy to Use: Get a public URL with a single command.

Building an Interactive Google Chat App with Node.js and Tunnelmole

Let's build a simple slash command. When a user types /greet in the chat, our bot will respond with a personalized greeting.

Step 1: Create the Express.js App

First, set up a basic Node.js Express server to handle incoming POST requests from Google Chat.

If you don't have a project, create one:

npm init -y
npm install express

Create a file named app.js:

const express = require('express');
const app = express();
const port = 8080;

// Google Chat sends JSON, so we need the JSON body parser
app.use(express.json());

// The endpoint that Google Chat will send POST requests to
app.post('/', (req, res) => {
  const event = req.body;
  console.log('Received event:', JSON.stringify(event, null, 2));

  let responseMessage;

  // Check if it's an interactive event triggered by a human
  if (event.type === 'MESSAGE' && event.message.slashCommand) {
    const commandId = event.message.slashCommand.commandId;

    // Respond to the "/greet" slash command
    if (commandId === '1') { // Google assigns a numeric ID to your slash command
      const userName = event.user.displayName;
      responseMessage = {
        text: `Hello, ${userName}! Thanks for using the Greet Bot.`
      };
    } else {
      responseMessage = { text: 'Sorry, I don\'t recognize that command.' };
    }
  } else if (event.type === 'ADDED_TO_SPACE') {
    responseMessage = { text: 'Thanks for adding me to this space! Try the /greet command.' };
  } else {
    // Ignore other event types for this simple bot
    return res.sendStatus(204); // No Content
  }

  // Send the response back to Google Chat
  res.json(responseMessage);
});

app.listen(port, () => {
  console.log(`Google Chat bot listening at http://localhost:${port}`);
});

This code creates a server on port 8080. It listens for POST requests on the root path (/), checks if the event is the /greet slash command, and sends back a simple text response.

Step 2: Install and Run Tunnelmole

Now, let's get a public URL for our local server. First, install Tunnelmole.

If you have Node.js installed, the easiest way is with npm:

sudo npm install -g tunnelmole

Alternatively, you can use the one-line installer for Linux, MacOS or WSL:

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

Once installed, start your Node.js application in one terminal:

node app.js
# Output: Google Chat bot listening at http://localhost:8080

In a second terminal, run Tunnelmole to expose port 8080:

tmole 8080

Tunnelmole will start and display your public URLs. Copy the HTTPS URL.

Your Tunnelmole Public URLs are below and are accessible internet wide. Always use HTTPs for the best security

https://kv2swd-ip-52-87-194-15.tunnelmole.net ⟶ http://localhost:8080
http://kv2swd-ip-52-87-194-15.tunnelmole.net ⟶ http://localhost:8080

Your public URL is now live and forwarding all traffic to your local server on port 8080.

Step 3: Configure Your App in the Google Cloud Console

Now, you need to tell Google about your bot and where to send events.

Go to the Google Cloud Console.
Create a new project or select an existing one.
Enable the "Google Chat API" for your project.
Navigate to the Google Chat API configuration page. Under the "Configuration" tab, fill out the App details:
- App Name: Greet Bot
- Avatar URL: An icon for your bot.
- Description: A simple bot that says hello.
Enable "Interactive features".
Under "Functionality", select "Receive 1:1 messages" and "Join spaces and group conversations".
In the Connection settings section:
- Select "App URL".
- Paste your Tunnelmole HTTPS URL into the text field.
Scroll down to "Slash Commands" and click "Add a slash command".
- Name: /greet
- Command ID: 1 (This must match the ID in your code)
- Description: Says hello to the user.
- Check the box for "Opens a dialog" (even though we're just sending a message, this is a common setup).
Click "Save". The status will change to "Live in production".
Go back to Google Chat, find your bot in the "Apps" section (you might need to add it), and try typing /greet.

When you run the command, Google Chat will send a POST request to your Tunnelmole URL. Tunnelmole will forward it to your localhost:8080 server. Your Express app will process the request, and you will see the full event logged to your console. Your bot will then reply with "Hello, [Your Name]!" in the chat.

Conclusion

Webhooks are the bridge between Google Chat and your external applications. You've learned how to:

Create incoming webhooks to push notifications and rich card messages into Google Chat spaces.
Use curl and Node.js to send these messages programmatically.
Handle outgoing webhooks to build interactive slash commands and bots.
Use Tunnelmole to get a public URL for your local development environment, drastically speeding up your development and testing cycle.

With these skills, you can now build powerful, custom integrations that bring your services and data directly into your team's collaborative workspace. Because Tunnelmole is open source, you have the flexibility to inspect the code, contribute to the project, or even host it yourself for complete control over your infrastructure.

Happy building!

Shopify Webhooks: The Complete Guide for Developers

Robbie Cahill — Sun, 31 Aug 2025 01:24:57 +0000

In the world of e-commerce, real-time data is king. Whether you're synchronizing orders, updating inventory, or connecting to a third-party service, the ability to react instantly to events is crucial for building modern, efficient applications. This is where Shopify Webhooks come in, serving as the backbone for countless app integrations and custom workflows.

However, for developers, working with webhooks presents a classic challenge: Shopify needs to send data to a public, internet-accessible URL, but your development environment runs on localhost. This disconnect can lead to slow, frustrating development cycles that involve constantly deploying code to a staging server just to test a small change.

This comprehensive guide will solve that problem for you. We'll dive deep into what Shopify webhooks are, why they're essential, and most importantly, how you can use an open-source tool called Tunnelmole to seamlessly test and debug your webhooks on your local machine.

By the end of this article, you'll have a complete workflow for building, testing, and securing a Shopify webhook handler using Node.js, from initial setup to production-ready best practices.

What are Shopify Webhooks?

At its core, a webhook is an automated message sent from an application when a specific event occurs. Think of it as a reverse API. Instead of your application repeatedly asking Shopify, "Is there a new order yet?", Shopify proactively tells your application, "Hey, a new order just came in!" by sending an HTTP POST request to a URL you specify.

This event-driven approach is incredibly powerful and efficient. It eliminates the need for constant polling, which saves server resources and provides you with data the moment it becomes available.

Common Use Cases for Shopify Webhooks

Developers leverage Shopify webhooks to build a vast array of features and integrations. Here are some of the most common use cases:

Order Fulfillment and Syncing: When an orders/create event happens, a webhook can instantly send the order details to a third-party logistics (3PL) provider or an internal inventory management system.
Customer Relationship Management (CRM): The customers/create event can trigger a webhook to add the new customer's details to a CRM like HubSpot or Salesforce, ensuring your marketing and sales teams have the latest data.
Product and Inventory Management: Using the products/update webhook, you can sync product details (like price or description) with other platforms or use inventory_levels/update to keep stock levels synchronized across multiple channels.
Custom Notifications: Send customized SMS, email, or Slack notifications for specific events, such as high-value orders (orders/paid) or abandoned checkouts (checkouts/create).
Data Warehousing and Analytics: Capture every order, product, and customer event and send it to a data warehouse for in-depth analysis and business intelligence reporting.

Shopify provides a comprehensive list of webhook topics, covering nearly every event that can happen in a store's lifecycle. You can subscribe to events related to carts, checkouts, orders, customers, products, and more. Each webhook delivery includes a JSON payload containing the relevant data for that event.

Here is an example of a JSON payload for a new order:

{
  "id": 2729912345678,
  "email": "customer@example.com",
  "created_at": "2025-07-04T10:30:00-04:00",
  "total_price": "59.99",
  "line_items": [
    {
      "sku": "TSHIRT-BLK-L",
      "name": "Black T-Shirt - Large",
      "quantity": 1,
      "price": "29.99"
    },
    {
      "sku": "STICKER-PACK",
      "name": "Awesome Sticker Pack",
      "quantity": 1,
      "price": "10.00"
    }
  ],
  "shipping_address": {
    "first_name": "John",
    "last_name": "Doe",
    "address1": "123 Fake St",
    "city": "Anytown",
    "zip": "12345",
    "country": "US"
  }
}

The Challenge: Testing Webhooks on Localhost

The primary hurdle in webhook development is the URL requirement. Shopify's servers exist on the public internet and need a public URL to send notifications. Your local development server, typically running at an address like http://localhost:3000, is only accessible on your own computer. Shopify has no way to reach it.

So, how do developers traditionally get around this?

Deploy on Every Change: The most common method is to deploy the code to a public staging or development server every time you make a change. This is incredibly inefficient. A simple logic change could require a full build and deployment process, turning a 30-second fix into a 10-minute task.
Manual Simulation: Another approach involves manually copying an example payload, pasting it into a tool like Postman or curl, and sending it to your local server. This is better than constant deployment, but it's tedious, error-prone, and doesn't accurately replicate the headers and metadata sent by Shopify, which are crucial for security and debugging.

Neither of these methods is ideal. They break your development flow, slow you down, and add unnecessary complexity. What you really need is a way to make your local server temporarily public.

The Solution: Tunnelmole for Effortless Local Development

This is where a tunneling tool becomes an essential part of your toolkit. Tunnelmole is an open-source application that creates a secure tunnel from a public URL to your local development environment.

When you run Tunnelmole, it generates a unique, public HTTPS URL (e.g., https://random-subdomain.tunnelmole.net). You can then provide this URL to Shopify. When Shopify sends a webhook to this URL, Tunnelmole forwards it through the tunnel directly to your application running on localhost.

This setup allows you to:

Receive Real Webhooks: Get actual, live webhook deliveries from Shopify directly to your local machine.
Use a Real Debugger: Set breakpoints in your code and step through your webhook handler line-by-line to inspect the payload, headers, and logic in real-time.
Iterate Quickly: Make a change to your code, save the file, and trigger the webhook again. No deployment needed.
Emphasize Open Source and Self-Hosting: Tunnelmole is fully open-source, meaning its code is transparent and can be audited. For maximum control and privacy, you can also self-host the Tunnelmole service on your own server.

Step-by-Step: Testing Shopify Webhooks with Node.js and Tunnelmole

Let's walk through the entire process of setting up a webhook handler, exposing it with Tunnelmole, and receiving a live test notification from Shopify.

Prerequisites

Node.js and npm: Make sure you have a recent version of Node.js installed.
A Shopify Partner Account and Development Store: This is free to create and allows you to test your apps and integrations safely.
A Text Editor: Such as VS Code.

Step 1: Create a Basic Express.js Server

First, let's create a simple Node.js application using the Express framework to listen for incoming webhooks.

Create a new project folder, initialize it with npm, and install Express:

mkdir shopify-webhook-handler
cd shopify-webhook-handler
npm init -y
npm install express

Now, create a file named server.js and add the following code. This sets up a web server with a single endpoint, /webhooks/orders, which will listen for POST requests.

const express = require('express');
const app = express();
const PORT = 3000;

// Use built-in middleware for parsing JSON.
// We'll modify this later for signature verification.
app.use(express.json());

app.get('/', (req, res) => {
  res.send('Shopify Webhook Handler is running!');
});

app.post('/webhooks/orders', (req, res) => {
  console.log('🎉 Received a new webhook!');
  console.log(JSON.stringify(req.body, null, 2));

  // Acknowledge receipt of the webhook with a 200 OK
  res.status(200).send('Webhook received');
});

app.listen(PORT, () => {
  console.log(`Server is listening on http://localhost:${PORT}`);
});

Run your server with node server.js. It's now listening for requests on your local port 3000.

Step 2: Install and Run Tunnelmole

Next, let's get a public URL. The easiest way to install Tunnelmole is using the script for Linux/Mac or by downloading the binary for Windows.

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

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

Alternatively, if you have Node.js installed, you can use npm:

sudo npm install -g tunnelmole

With your local server running on port 3000, open a new terminal window and run:

tmole 3000

Tunnelmole will start and display your public URLs. Copy the HTTPS URL—it will look something like this:

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:3000
http://cqcu2t-ip-49-185-26-79.tunnelmole.net ⟶ http://localhost:3000

This public URL is now forwarding all traffic directly to your local server on port 3000.

Step 3: Create the Webhook in Shopify

Now, let's tell Shopify where to send its webhook notifications.

Log in to your Shopify development store's admin panel.
Navigate to Settings in the bottom-left corner, then click on Notifications.
Scroll all the way down to the Webhooks section and click Create webhook.
Fill out the form:
- Event: Select the event you want to subscribe to. Let's use Order creation for this example.
- Format: Choose JSON.
- URL: Paste your public Tunnelmole URL, followed by the path to your webhook handler. For our example, this would be: https://cqcu2t-ip-49-185-26-79.tunnelmole.net/webhooks/orders.
- Webhook API version: Select the latest stable version.
Click Save.

Your webhook is now active.

Step 4: Trigger a Test Webhook

You can now trigger a test event in two ways:

From the Shopify Admin: On the Webhooks page, you'll see your newly created webhook. Click the Send test notification button next to it.
Perform the Action: Alternatively, you can perform the actual action in your store. Since we subscribed to Order creation, just create a draft order and mark it as paid.

Go back to the terminal where your Node.js server is running. You should see the webhook payload printed to the console!

🎉 Received a new webhook!
{
  "id": 1234567890123,
  "name": "#1001",
  // ... and the rest of the order data
}

You have successfully received a live Shopify webhook on your local machine. You can now set a breakpoint in your /webhooks/orders handler and use a debugger to inspect the request in detail.

Securing Your Shopify Webhook: Signature Verification

Receiving webhooks is great, but in a production environment, you must verify that they are actually coming from Shopify. Otherwise, anyone who discovers your webhook URL could send you fake data.

Shopify solves this by signing each webhook request with a secret key. When you create a webhook, Shopify generates a secret that is shared only between your app and Shopify. Each request includes a header, X-Shopify-Hmac-Sha256, containing a cryptographic signature.

Your job is to calculate the same signature on your end and ensure it matches the one Shopify sent.

Step 1: Update Your Server for HMAC Verification

First, you need the raw request body to generate the signature. The express.json() middleware modifies the body, so we need to use express.raw instead for our webhook endpoint. You'll also need Node's built-in crypto module.

Update your server.js file:

const express = require('express');
const crypto = require('crypto');
const app = express();
const PORT = 3000;

// IMPORTANT: Your Shopify Webhook Secret Key
const SHOPIFY_WEBHOOK_SECRET = 'your_shared_secret_from_shopify_dashboard';

// Middleware to verify the webhook signature
const verifyShopifyWebhook = (req, res, buf, encoding) => {
  const hmacHeader = req.get('X-Shopify-Hmac-Sha256');
  if (!hmacHeader) {
    console.error('Webhook missing X-Shopify-Hmac-Sha256 header');
    throw new Error('Webhook verification failed: Missing HMAC header');
  }

  const hash = crypto
    .createHmac('sha256', SHOPIFY_WEBHOOK_SECRET)
    .update(buf, encoding)
    .digest('base64');

  // Use crypto.timingSafeEqual to prevent timing attacks
  const hmacBuffer = Buffer.from(hmacHeader, 'base64');
  const hashBuffer = Buffer.from(hash, 'base64');

  if (!crypto.timingSafeEqual(hmacBuffer, hashBuffer)) {
    console.error('Webhook verification failed: HMAC mismatch');
    throw new Error('Webhook verification failed: Signature mismatch');
  }

  console.log('✅ Webhook signature verified successfully');
};


app.get('/', (req, res) => {
  res.send('Shopify Webhook Handler is running!');
});

// Apply the raw body parser and our verification middleware ONLY to the webhook route
app.post('/webhooks/orders', express.raw({ type: 'application/json' }), (req, res, next) => {
  try {
    verifyShopifyWebhook(req, res, req.body, 'utf8');
    // If verification passes, parse the JSON body and continue
    req.body = JSON.parse(req.body.toString());
    next();
  } catch (error) {
    res.status(401).send(error.message);
  }
}, (req, res) => {
  console.log('🎉 Received a new verified webhook!');
  console.log(JSON.stringify(req.body, null, 2));

  res.status(200).send('Webhook received and verified');
});

app.listen(PORT, () => {
  console.log(`Server is listening on http://localhost:${PORT}`);
});

Step 2: Get Your Webhook Secret Key

Go back to your webhook's configuration page in the Shopify admin (Settings > Notifications > Webhooks). You will see the shared secret displayed. Click to reveal it, copy it, and paste it into the SHOPIFY_WEBHOOK_SECRET constant in your server.js file.

Restart your Node server and send another test notification. This time, you should see the "Webhook signature verified successfully" message in your console, confirming that your security check is working correctly. If you try to send a request with an invalid signature (e.g., from Postman without the correct HMAC header), the server will correctly reject it with a 401 Unauthorized error.

Production Best Practices

With your handler working and secured, consider these best practices for a production-grade system:

Asynchronous Processing: A webhook handler should response immediately with a 200 OK status to let Shopify know it received the event. Don't perform long-running tasks like calling another API or processing a large file directly in the request handler. This can lead to timeouts. Instead, use a background job queue (e.g., BullMQ, RabbitMQ) to process the data asynchronously.
Idempotency: Shopify's system guarantees "at-least-once" delivery, which means in rare cases, you might receive the same webhook more than once. Design your handler to be idempotent—meaning it can safely process the same event multiple times without causing issues. A common strategy is to log the id of each received event and skip any duplicates.
Error Handling and Monitoring: Implement robust logging to track incoming webhooks and any errors that occur during processing. Set up monitoring and alerts to notify you if your endpoint starts failing, as Shopify will stop sending webhooks to an endpoint that fails repeatedly.
API Versioning: Webhooks are tied to a specific Shopify API version. Shopify periodically releases new versions and retires old ones. Be sure to subscribe to a stable API version and have a plan for upgrading your code before your current version is sunset.

Conclusion

Shopify webhooks are a powerful tool for creating dynamic, event-driven e-commerce applications. While local development has traditionally been a bottleneck, tools like the open-source Tunnelmole completely change the game. By creating a secure, public tunnel to your local machine, you can accelerate your development workflow, debug issues in real-time, and build more reliable integrations.

By following this guide, you now have a complete, secure, and efficient process for handling Shopify webhooks with Node.js. You can receive live events, verify their authenticity, and focus on building great features instead of fighting with deployment pipelines.

Ready to streamline your Shopify development? Get started with Tunnelmole today and see how easy local webhook testing can be.

GitHub Webhook: A Complete Guide to Automation

Robbie Cahill — Sun, 31 Aug 2025 01:23:34 +0000

In the world of modern software development, automation is the key to efficiency, consistency, and speed. One of the most powerful tools for automation within the developer ecosystem is the GitHub webhook. Whether you're looking to build a CI/CD pipeline, send notifications to Slack, or trigger custom deployment scripts, understanding GitHub webhooks is a fundamental skill.

This comprehensive guide will walk you through everything you need to know about GitHub webhooks. We'll start with the basics, build a real-world example using Node.js, and show you how to securely test your integration locally using open-source tools. By the end, you'll be able to confidently integrate GitHub webhooks into your own projects to automate your workflows.

What Exactly is a Webhook?

Before diving into the specifics of GitHub, it's crucial to understand the core concept of a webhook.

Traditionally, if you wanted to know if a status changed in another system (like a new sale on your e-commerce store), you would have to constantly ask it, "Is there anything new? Is there anything new? Is there anything new?" This process is called polling. It's inefficient, resource-intensive, and there's always a delay between the event happening and your system finding out about it.

Webhooks flip this model on its head. Instead of you asking for new information, the service tells you about it the moment it happens. This is often described as a "reverse API."

Here’s a simple breakdown:

You provide a URL (your webhook endpoint) to a service (the webhook provider).
You tell the provider which events you're interested in (e.g., a "new purchase").
When that event occurs, the provider immediately sends an HTTP request (usually a POST request) to your URL with a payload of data describing the event.
Your application, which is listening at that URL, receives the data and can take immediate action.

This event-driven approach is far more efficient and enables real-time integrations between different services.

Understanding the GitHub Webhook Ecosystem

A GitHub webhook works on the exact principles described above. You can configure your GitHub repository to send a webhook payload to a specified URL whenever a certain event occurs. The range of events GitHub supports is vast, making it an incredibly powerful tool for automation.

Some of the most common events you can subscribe to include:

push: Triggered whenever a commit is pushed to a branch. This is the cornerstone of most CI/CD pipelines.
pull_request: Triggered when a pull request is opened, closed, reopened, or synchronized. Essential for code review automation.
issues: Triggered when an issue is opened, edited, closed, or labeled. Useful for project management integrations.
release: Triggered when a new release is published. Perfect for automating deployment notifications or package publishing.
fork: Triggered when a repository is forked.
workflow_run: Triggered when a GitHub Actions workflow is requested or completed.

Each event sends a unique payload—a JSON body containing detailed information about the event. For example, a push event payload includes the repository name, the branch that was pushed to, the commit hashes, the author's details, and more. Your application can parse this JSON to perform context-aware actions.

Building Our First GitHub Webhook Receiver

The best way to learn is by doing. We're going to build a simple webhook receiver that listens for push events from a GitHub repository. When a push occurs, our application will log the committer's name and the commit message to the console.

To do this, we need three key components:

A web server running locally to act as our webhook endpoint.
A way to give our local server a public URL that GitHub can reach.
A webhook configured in our GitHub repository to point to that public URL.

Prerequisites

Node.js and npm: Make sure you have a recent version of Node.js installed. You can get it from nodejs.org.
A GitHub Account: You'll need an account and a repository to test with. If you don't have one, create a new demo repository.
A Text Editor: Visual Studio Code or any other editor of your choice.

Step 1: Create a Local Web Server with Express.js

We'll use Express.js, a minimal and flexible Node.js web application framework, to create our server.

First, create a new project directory and initialize it with npm.

mkdir github-webhook-receiver
cd github-webhook-receiver
npm init -y

Now, install Express:

npm install express

Next, create a file named app.js and add the following code:

/*
 * app.js - A simple Express server to receive GitHub webhooks.
 */

const express = require('express');

// Create the Express app
const app = express();
const port = 8080;

// Middleware to parse JSON bodies. GitHub sends webhooks as JSON.
// We need the raw body for signature verification, so we'll use a custom parser.
app.use(express.json({
    verify: (req, res, buf) => {
        req.rawBody = buf;
    }
}));


// Define the endpoint for our GitHub webhook
app.post('/github-webhook', (req, res) => {
    // The event type is in the X-GitHub-Event header
    const githubEvent = req.headers['x-github-event'];

    console.log(`Received a webhook for the '${githubEvent}' event`);
    console.log('---');

    // We're only interested in 'push' events for this demo
    if (githubEvent === 'push') {
        const payload = req.body;

        // Extract relevant information from the push payload
        const repositoryName = payload.repository.full_name;
        const commitAuthor = payload.head_commit.author.name;
        const commitMessage = payload.head_commit.message;
        const branch = payload.ref.split('/').pop();

        console.log(`New push to repository: ${repositoryName}`);
        console.log(`Branch: ${branch}`);
        console.log(`Author: ${commitAuthor}`);
        console.log(`Commit Message: "${commitMessage}"`);
    }

    // Always respond with a 200 OK to let GitHub know the webhook was received successfully.
    // If GitHub doesn't receive a 2xx response, it will consider the delivery a failure
    // and may retry, leading to duplicate processing.
    res.status(200).send('Webhook received.');
});

// A simple root endpoint to confirm the server is running
app.get('/', (req, res) => {
    res.send('Server is up and running. Ready to receive GitHub webhooks at /github-webhook.');
});

// Start the server
app.listen(port, () => {
    console.log(`Server started on http://localhost:${port}`);
});

Let's break down this code:

We initialize an Express app and tell it to listen on port 8080.
Crucially, we use express.json() to parse incoming JSON payloads from GitHub.
We define a single endpoint: POST /github-webhook. This is the URL we'll give to GitHub.
Inside the handler, we check the x-github-event header to ensure it's a push event.
We then parse the req.body (the JSON payload) to extract and log the repository name, author, and commit message.
Finally, we send a 200 OK response. This is vital. If GitHub doesn't get a 2xx response, it will assume the delivery failed and retry, which could cause your automation to run multiple times for a single event.

Start your server by running:

node app.js

You should see the message: Server started on http://localhost:8080. If you visit http://localhost:8080 in your browser, you'll see our confirmation message.

Step 2: Expose Your Local Server with Tunnelmole

Our server is running, but it's only accessible on localhost. GitHub's servers on the public internet have no way to reach it. We need to create a secure tunnel from a public URL to our local machine.

This is where Tunnelmole comes in. Tunnelmole is an open-source tool that creates a public HTTPS URL for your locally running servers. It's simple, fast, and perfect for testing webhooks.

First, install Tunnelmole. The simplest way is to use the install script for Linux, Mac, or WSL.

# For Linux, macOS, and WSL
curl -O https://install.tunnelmole.com/xD345/install && sudo bash install

For Windows users, you can download the executable and add it to your PATH. Visit the Tunnelmole website for the latest installation instructions.

Once installed, open a new terminal window (leave your Node.js server running in the first one) and run the following command, telling Tunnelmole to forward traffic to your local port 8080.

tmole 8080

Tunnelmole will start and generate a unique public URL that forwards to your local server. The output will look something like this:

$ tmole 8080
Your Tunnelmole Public URLs are below and are accessible internet wide. Always use HTTPs for the best security

https://k2e6yq-ip-12-34-56-78.tunnelmole.net ⟶ http://localhost:8080
http://k2e6yq-ip-12-34-56-78.tunnelmole.net ⟶ http://localhost:8080

Copy the https URL. This is the public address for your webhook. Anyone on the internet can now send requests to this URL, and they will be securely tunneled to your Express app running on localhost:8080.

How Does Tunnelmole Work?

Tunnelmole works by establishing a secure, persistent connection from the client on your machine to the Tunnelmole service in the cloud. When a request hits your public URL, the service sends it down this tunnel to your local client, which then forwards it to your local server.

A key advantage of Tunnelmole is that it's fully open source, including the server component. This means you have the option to self-host the entire service for maximum privacy and control, which is a great option for corporate environments with strict data policies.

Step 3: Configure the Webhook in Your GitHub Repository

Now we have all the pieces. Let's wire them together.

Go to the GitHub repository you want to use for testing.
Click on the "Settings" tab.
In the left sidebar, click on "Webhooks".
Click the "Add webhook" button in the top right.

You'll see a configuration form. Fill it out as follows:

Payload URL: Paste your HTTPS Tunnelmole URL here, and append your endpoint path /github-webhook. For example: https://k2e6yq-ip-12-34-56-78.tunnelmole.net/github-webhook
Content type: Select application/json. Our Express app is configured to parse JSON.
Secret: This is a critical field for security. Create a strong, random string to use as a secret and paste it here. You can use a password generator for this. We'll see how to use this secret in the next section. For now, let's say our secret is this-is-a-very-secret-string-12345.
Which events would you like to trigger this webhook?: For this demo, select "Just the push event." In a real-world scenario, you might want to select "Send me everything" or manually choose specific events.

Finally, click the "Add webhook" button at the bottom of the form.

Step 4: Test Your GitHub Webhook!

As soon as you add the webhook, GitHub sends a special ping event to your Payload URL to verify that it's reachable.

Look at your running Node.js server's terminal. You should see output like this:

Received a webhook for the 'ping' event
---

This confirms that the entire chain is working: GitHub -> Tunnelmole -> Your Local Express App.

Now for the real test. Make a change in your local repository, commit it, and push it to GitHub.

# Make a change, for example, edit your README.md
echo "Testing my new webhook" >> README.md

# Commit and push
git add .
git commit -m "feat: Implement amazing new feature"
git push

As soon as the push is complete, check your server's terminal again. This time, you'll see the detailed output from our push event handler:

Received a webhook for the 'push' event
---
New push to repository: your-username/github-webhook-receiver
Branch: main
Author: Your Name
Commit Message: "feat: Implement amazing new feature"

Success! You have successfully created, configured, and tested a github webhook that communicates with a server on your local machine.

Securing Your Webhook Endpoint

Our current setup works, but it has a major security flaw. The Tunnelmole URL is public. Anyone who finds it could send fake POST requests to our endpoint, pretending to be GitHub and potentially triggering our automation with malicious data.

This is why GitHub has the "Secret" field. When you set a secret, GitHub uses it to create a hash-based message authentication code (HMAC) signature for each webhook payload. This signature is sent with the request in the X-Hub-Signature-256 header.

Your application can then compute its own signature using the same secret and compare it with the one sent by GitHub. If they match, you can be 100% certain the request is authentic and came from GitHub.

Let's update our app.js to implement this verification.

First, install the built-in crypto module (it comes with Node.js, so no npm install is needed). We'll also use an environment variable to store our secret securely instead of hardcoding it.

Update app.js:

/*
 * app.js - A SECURE Express server to receive GitHub webhooks.
 */

const express = require('express');
const crypto = require('crypto'); // Built-in Node.js module

const app = express();
const port = 8080;

// Get the webhook secret from an environment variable for security
const GITHUB_WEBHOOK_SECRET = process.env.GITHUB_WEBHOOK_SECRET;

if (!GITHUB_WEBHOOK_SECRET) {
    console.error('Error: GITHUB_WEBHOOK_SECRET environment variable not set.');
    process.exit(1);
}

// Middleware to parse JSON bodies.
// IMPORTANT: We need the raw request body (a buffer) to verify the signature.
// The `verify` function lets us capture it.
app.use(express.json({
    verify: (req, res, buf) => {
        req.rawBody = buf;
    }
}));

// A middleware function to verify the GitHub signature
function verifyGitHubSignature(req, res, next) {
    const signatureHeader = req.headers['x-hub-signature-256'];
    if (!signatureHeader) {
        return res.status(401).send('Unauthorized: No signature provided.');
    }

    // Create our own signature using the secret and the raw request body
    const hmac = crypto.createHmac('sha256', GITHUB_WEBHOOK_SECRET);
    hmac.update(req.rawBody);
    const expectedSignature = `sha256=${hmac.digest('hex')}`;

    console.log(`Received Signature: ${signatureHeader}`);
    console.log(`Expected Signature: ${expectedSignature}`);

    // Use a timing-safe comparison to prevent timing attacks
    const isSignatureValid = crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expectedSignature));

    if (!isSignatureValid) {
        return res.status(401).send('Unauthorized: Invalid signature.');
    }

    // If the signature is valid, proceed to the next middleware/handler
    next();
}


// Apply the verification middleware ONLY to our webhook endpoint
app.post('/github-webhook', verifyGitHubSignature, (req, res) => {
    const githubEvent = req.headers['x-github-event'];
    console.log(`Received a verified webhook for the '${githubEvent}' event`);
    console.log('---');

    if (githubEvent === 'push') {
        const payload = req.body;
        const repositoryName = payload.repository.full_name;
        const commitAuthor = payload.head_commit.author.name;
        const commitMessage = payload.head_commit.message;
        const branch = payload.ref.split('/').pop();

        console.log(`New push to repository: ${repositoryName}`);
        console.log(`Branch: ${branch}`);
        console.log(`Author: ${commitAuthor}`);
        console.log(`Commit Message: "${commitMessage}"`);
    }

    res.status(200).send('Webhook received and verified.');
});

app.get('/', (req, res) => {
    res.send('Server is up and running. Ready to receive GitHub webhooks at /github-webhook.');
});

app.listen(port, () => {
    console.log(`Server started on http://localhost:${port}`);
});

Key changes:

We read the secret from process.env.GITHUB_WEBHOOK_SECRET.
We created a middleware function verifyGitHubSignature.
Inside the middleware, we compute our own HMAC SHA256 signature from the raw request body buffer (req.rawBody) that we cleverly saved earlier.
We use crypto.timingSafeEqual to compare our signature with the one from the header. This is important to prevent timing attacks.
If the signatures don't match, we immediately send a 401 Unauthorized and stop processing.
We apply this middleware specifically to our /github-webhook route.

Now, restart your server with the secret set as an environment variable. Replace the secret with the one you configured in the GitHub UI.

# On Linux/macOS
GITHUB_WEBHOOK_SECRET="this-is-a-very-secret-string-12345" node app.js

# On Windows (Command Prompt)
set GITHUB_WEBHOOK_SECRET="this-is-a-very-secret-string-12345"
node app.js

To test this, go back to your webhook settings in GitHub, click "Edit", and go to the "Recent Deliveries" tab at the bottom. Click the three dots next to the last delivery and select "Redeliver." GitHub will send the same payload again. This time, your secure server will verify the signature before processing it.

Conclusion

The GitHub webhook is a gateway to powerful automation. By understanding how to create, secure, and test webhook endpoints, you can build seamless CI/CD pipelines, integrate with project management tools, create custom notifications, and much more.

In this guide, we've walked through the entire process:

We learned the fundamentals of webhooks.
We built a Node.js and Express server to act as a webhook receiver.
We used the open-source tool Tunnelmole to expose our local server to the internet for easy and fast testing.
We configured a github webhook in our repository to send push events to our server.
Most importantly, we secured our endpoint by verifying the HMAC signature, ensuring that we only process legitimate requests from GitHub.

The combination of a flexible local server and a secure tunneling tool like Tunnelmole provides the perfect development environment for building and debugging any webhook integration. You can now apply these principles to any webhook provider, not just GitHub, to build robust, event-driven applications.

How to Test WhatsApp Webhooks Locally in 5 Minutes

Robbie Cahill — Sun, 31 Aug 2025 01:22:13 +0000

Developing applications that integrate with the WhatsApp Business Platform offers incredible opportunities to engage with users. A core component of this integration is webhooks, which allow WhatsApp to send you real-time notifications about events, such as incoming messages. However, there's a significant hurdle for developers: WhatsApp requires a public HTTPS URL to send these notifications, but your development environment runs on localhost, which isn't accessible from the public internet.

This guide solves that exact problem. You'll learn how to securely expose your local development server to the internet to receive WhatsApp webhooks, enabling you to build and test your integration in a fast, efficient feedback loop. We'll use a simple Node.js and Express application as our webhook receiver and an open-source tool called Tunnelmole to create the necessary public URL.

By the end of this comprehensive guide, you will be able to:

Understand the role and importance of WhatsApp webhooks.
Build a basic webhook handler in Express.js to process WhatsApp notifications.
Install and use Tunnelmole to get a secure, public HTTPS URL for your local server.
Configure your Meta Developer App to send webhooks to your local environment.
Test and debug your WhatsApp integration in real-time.

What are WhatsApp Webhooks?

WhatsApp Webhooks are automated messages sent from an application (in this case, WhatsApp) to your server when a specific event occurs. They are the backbone of building interactive and responsive applications on the WhatsApp Business Platform. Instead of you repeatedly asking the WhatsApp API if there's a new message (a process called polling), WhatsApp proactively tells you by sending an HTTP request to a "callback URL" that you provide.

These webhooks can notify you of various events, including:

New Messages: When a user sends a message to your business number (text, images, audio, etc.).
Message Status Changes: When a message you sent is delivered, read, or fails.
Account Updates: Changes to your WhatsApp Business Account status.
User Interactions: When a user clicks a button in one of your interactive messages.

To use webhooks, you need to set up a WhatsApp Business App through the Meta for Developers platform. During setup, WhatsApp will ask for a Callback URL. This URL must be a public, HTTPS-secured endpoint that WhatsApp's servers can reach. This is where the challenge of local development arises, and where a tunneling tool becomes essential.

Why You Need a Tunnel for Local Development

When you run a web server on your local machine, it typically listens on an address like http://localhost:3000 or http://127.0.0.1:3000. This address is only accessible from your own computer. For security reasons, your router and operating system firewall block incoming requests from the public internet to your localhost.

However, for a service like WhatsApp to send you a webhook, it needs to be able to make a POST request to your server from its own infrastructure out on the internet. It has no way of reaching localhost:3000 on your machine directly.

This is where a tunneling service comes in. A tunnel creates a secure connection from your local machine to a public server. It provides you with a publicly accessible URL (e.g., https://random-subdomain.tunnelmole.net) that forwards all incoming traffic through the secure tunnel to your local server.

Using a tunnel allows you to:

Receive Real Webhooks: Test your application with actual, live data from WhatsApp.
Avoid Mocking: You don't need to create fake webhook payloads or stub requests, which can be inaccurate and time-consuming.
Debug in Real-Time: Set breakpoints in your code and inspect the live request from WhatsApp as it hits your local machine.
Accelerate Development: Get instant feedback on code changes without deploying to a staging or production server.

Introducing Tunnelmole: Your Open Source Tunneling Solution

Tunnelmole is a simple, fast, and open-source tool that gives your locally running servers a public URL. It’s designed to be straightforward, allowing you to get a tunnel up and running with a single command.

Key features of Tunnelmole that make it ideal for this task include:

Open Source: The code for both the Tunnelmole client and server is publicly available on GitHub. This transparency allows you to inspect the code and understand exactly how it works.
Free to Use: Tunnelmole's hosted service provides free public URLs that are perfect for development and testing.
Optionally Self-Hostable: For advanced use cases, enhanced security, or custom domain needs, you can host the Tunnelmole service on your own infrastructure. This gives you complete control over your tunneling environment.
Easy Installation: It's a native NodeJS application that can be installed via a simple script or NPM, with no complex dependencies.

Step-by-Step Guide: Testing WhatsApp Webhooks with Tunnelmole

Let's walk through the entire process from creating a local webhook handler to receiving a live notification from WhatsApp.

Prerequisites

Node.js and npm: Ensure you have Node.js (version 16.10 or later) and npm installed.
WhatsApp Business Account: You need access to the WhatsApp Business Platform. You can set this up through the Meta for Developers portal.
A Test Phone Number: You'll need a personal WhatsApp number to send a message to your business test number.

Step 1: Create a Simple Express.js Webhook Receiver

First, let's create a small Node.js server using the Express framework. This server will have two endpoints required by WhatsApp:

A GET endpoint for the initial verification handshake.
A POST endpoint to receive the actual webhook data.

Create a new project folder, cd into it, and initialize a Node.js project.

mkdir whatsapp-webhook-test
cd whatsapp-webhook-test
npm init -y
npm install express body-parser

Now, create a file named index.js and add the following code:

/*
  A simple Express.js server to handle WhatsApp webhook verification and notifications.
*/
const express = require('express');
const bodyParser = require('body-parser');

const app = express();
app.use(bodyParser.json());

const PORT = process.env.PORT || 3000;
// This is the verification token you'll set in the Meta Developer App dashboard.
// It's a secret that you and WhatsApp both know.
const VERIFY_TOKEN = "YOUR_SECRET_VERIFICATION_TOKEN";

// Endpoint for WhatsApp to verify your webhook
app.get('/webhook', (req, res) => {
    console.log("Received a verification request.");

    // Parse the query params
    const mode = req.query['hub.mode'];
    const token = req.query['hub.verify_token'];
    const challenge = req.query['hub.challenge'];

    // Checks if a token and mode is in the query string of the request
    if (mode && token) {
        // Checks the mode and token sent are correct
        if (mode === 'subscribe' && token === VERIFY_TOKEN) {
            // Responds with the challenge token from the request
            console.log('WEBHOOK_VERIFIED');
            res.status(200).send(challenge);
        } else {
            // Responds with '403 Forbidden' if verify tokens do not match
            console.error("Verification failed. Tokens do not match.");
            res.sendStatus(403);
        }
    } else {
        res.sendStatus(400); // Bad Request if mode or token is missing
    }
});

// Endpoint for receiving webhook notifications
app.post('/webhook', (req, res) => {
    console.log("Received a webhook notification.");

    const { body } = req;

    // Log the entire payload to inspect it
    console.log(JSON.stringify(body, null, 2));

    // You can now process the webhook payload.
    // For example, check if it's a message notification:
    if (body.object === 'whatsapp_business_account') {
        body.entry.forEach(entry => {
            entry.changes.forEach(change => {
                if (change.field === 'messages') {
                    const message = change.value.messages[0];
                    console.log(`New message from ${message.from}: ${message.text.body}`);
                    // Here you would add your logic to reply or process the message.
                }
            });
        });
    }

    // Respond with a 200 OK to acknowledge receipt of the event
    res.sendStatus(200);
});

app.listen(PORT, () => console.log(`Webhook server is listening on port ${PORT}`));

Remember to replace "YOUR_SECRET_VERIFICATION_TOKEN" with a unique, secret string of your own.

Run your server:

node index.js

Your server is now running locally and listening on port 3000.

Step 2: Install and Run Tunnelmole

With your local server running, the next step is to give it a public URL.

Install Tunnelmole by running the following command in your terminal. This script will detect your OS and install the correct version.

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

For Windows, you can download the executable directly and place it in your PATH.

Now, run Tunnelmole and point it to the port your Express app is using (3000).

tmole 3000

Tunnelmole will start and display your public URLs.

$ tmole 3000
Your Tunnelmole Public URLs are below and are accessible internet wide. Always use HTTPs for the best security

https://k8sctb-ip-1-2-3-4.tunnelmole.net ⟶ http://localhost:3000
http://k8sctb-ip-1-2-3-4.tunnelmole.net ⟶ http://localhost:3000

Copy the HTTPS URL (e.g., https://k8sctb-ip-1-2-3-4.tunnelmole.net). This is the URL you will give to WhatsApp.

Step 3: Configure Your WhatsApp Webhook

Go to the Meta for Developers dashboard.
Select the app you created for WhatsApp Business.
From the sidebar, navigate to WhatsApp > Configuration.
In the "Webhooks" section, click Edit.
A dialog box will appear. Here you need to enter the Callback URL and Verification Token.
- Callback URL: Paste your Tunnelmole HTTPS URL here, and append /webhook to the end (e.g., https://k8sctb-ip-1-2-3-4.tunnelmole.net/webhook).
- Verify Token: Enter the exact same secret token you defined as VERIFY_TOKEN in your index.js file.
Click Verify and save.

When you click "Verify and save", WhatsApp will send a GET request to your Tunnelmole URL. Tunnelmole forwards this to your local server. Your Express app will check the token, and if it matches, it will respond with the challenge code. You should see "WEBHOOK_VERIFIED" logged in your local server's console. If everything is correct, the dialog will close, and your webhook will be active.

Step 4: Subscribe to Webhook Fields

After successful verification, you need to tell WhatsApp which events you want to be notified about.

Back on the WhatsApp > Configuration page, find your webhook and click Manage.
This will bring up a list of all available webhook "fields."
Find the messages field and click Subscribe. This tells WhatsApp to notify you about all message-related events.

Step 5: Test the Integration

Now for the exciting part! Let's test the end-to-end flow.

From your personal WhatsApp account, send a message to the test number associated with your WhatsApp Business App.
Watch the console where your local Node.js server is running.

You should immediately see the full webhook payload logged to your console, similar to this:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "123456789012345",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "16505551111",
              "phone_number_id": "987654321098765"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Your Name"
                },
                "wa_id": "14155552671"
              }
            ],
            "messages": [
              {
                "from": "14155552671",
                "id": "wamid.HBgLMTQxNTU1NTI2NzEVAgARGBJDNzI4Q0Q4MTQ0N0JBRTdGRDAA",
                "timestamp": "1668631112",
                "text": {
                  "body": "Hello from my phone!"
                },
                "type": "text"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

You will also see the specific log message: New message from 14155552671: Hello from my phone!.

Congratulations! You are now receiving live WhatsApp webhooks on your local machine. You can now set breakpoints in your index.js file, modify the code, and test your logic in real-time without ever needing to deploy your changes.

Security and Best Practices

When moving to production, always validate the request signature. WhatsApp signs each webhook request with your app's secret key using HMAC-SHA256. This is sent in the X-Hub-Signature-256 HTTP header. Verifying this signature ensures that the request genuinely came from WhatsApp and was not tampered with. This step is crucial for securing your production webhook endpoint.

Conclusion

Testing webhooks is a common pain point in modern API development. For services like the WhatsApp Business Platform, a public callback URL is non-negotiable, which often forces developers into slow, cumbersome deployment cycles just to test a small change.

By using Tunnelmole, you can bridge the gap between your local development environment and the public internet. This guide has shown you how to set up a Node.js server, generate a public HTTPS URL with a single command, and configure WhatsApp to send live webhook events directly to your laptop. This workflow dramatically speeds up development, improves debugging, and ultimately helps you build more reliable integrations faster.

Because Tunnelmole is open source and can be self-hosted, it offers a flexible and powerful solution that scales with your needs, from a quick test to a permanent development tool.

Download Tunnelmole and start building your next WhatsApp integration today with a faster, more efficient development loop.

WP Webhooks: The Ultimate Guide to Connecting WordPress to Anything (2025)

Robbie Cahill — Sun, 31 Aug 2025 01:20:21 +0000

In the modern digital ecosystem, standalone applications are a rarity. The real power comes from integration—making different systems talk to each other to automate workflows, sync data, and create seamless user experiences. For the millions of websites powered by WordPress, this integration is often handled by WP Webhooks. They are the invisible bridges that connect your WordPress site to the vast world of APIs, SaaS products, and custom applications.

However, developing and testing these crucial integrations comes with a significant challenge: how do you allow external services on the public internet to communicate with a WordPress instance running on your local machine? This is where developers often get stuck.

This ultimate guide will not only teach you everything you need to know about WP Webhooks but also provide a clear, actionable solution to this local development problem using Tunnelmole, a simple and open-source tunneling tool.

We will cover:

What webhooks are and why they are superior to traditional API polling.
Practical use cases for automating your WordPress site.
The step-by-step process of creating a custom webhook listener in a WordPress plugin.
How to use Tunnelmole to expose your local WordPress environment to the internet for testing.
Essential security practices to protect your webhook endpoints.

What Are WP Webhooks and Why Should You Care?

Think of a webhook as a "reverse API" or a doorbell for your website.

With a traditional API, you are responsible for asking for new information. For example, your WordPress site might have to poll a CRM's API every five minutes to ask, "Is there a new contact? ... Is there a new contact now? ... How about now?" This is inefficient, resource-intensive, and results in delayed updates.

Webhooks flip this model on its head. Instead of your site constantly asking for data, the external service automatically sends the data to your WordPress site the moment an event happens. The external service "rings the doorbell" of your website, delivering the information as a payload of data. Your website’s job is to "answer the door" by listening for this incoming request and then taking an appropriate action.

Key Benefits of Using Webhooks with WordPress

Real-Time Speed: Data is pushed from the source to your WordPress site the instant an event occurs. This is essential for time-sensitive workflows like inventory management, user notifications, and financial transactions.
Improved Performance and Efficiency: Your server isn't burdened with running constant API polling requests. This saves CPU cycles, reduces database load, and can lead to a faster website. Webhooks are a "set it and forget it" mechanism that consumes resources only when there's new information.
Powerful Automation: Webhooks are the glue for automation platforms like Zapier, IFTTT, and custom integration hubs. They enable you to chain actions across multiple systems, triggered by an event in your WordPress site or an external application.
Limitless Integration: Any application that can send an HTTP request can integrate with your WordPress site through webhooks, opening up a universe of possibilities beyond the official plugins available in the WordPress repository.

Common Use Cases for WordPress Webhooks

The possibilities are nearly endless, but here are some popular and powerful ways developers and businesses use WP Webhooks:

E-commerce (WooCommerce): Instantly update an external inventory management system when a product is sold, notify a shipping provider to prepare a delivery, or add a customer to a marketing automation sequence after their first purchase.
User Management: Sync new WordPress user registrations to a central CRM like Salesforce or HubSpot, assign roles based on data from an external system, or send a personalized welcome sequence through a service like Mailchimp.
Content Workflows: Send a notification to a Slack channel when a new post is published for review, automatically share new blog posts on social media, or trigger a backup service whenever a page is updated.
Form Submissions: Connect forms built with Gravity Forms, Contact Form 7, or WPForms to a Google Sheet, a project management tool like Trello, or a customer support ticketing system.
DevOps and CI/CD: Trigger a static site rebuild on a service like Netlify or Vercel whenever content is updated in the WordPress admin, clearing the cache and deploying the latest version.

The Challenge: Testing Webhooks on a Local WordPress Site

Here's the fundamental problem every WordPress developer encounters when working with webhooks. Your local development environment, whether it's powered by XAMPP, MAMP, or Docker, runs on a private address like localhost or 127.0.0.1. This address is only accessible from your computer.

Webhook providers like Stripe, GitHub, or Zapier live on the public internet. They have no way of reaching http://localhost:8080 on your machine. To them, it doesn't exist.

So how can you test that your custom webhook handler works correctly? The traditional, painful methods include:

Deploying on every change: Pushing your code to a staging server every time you make a small adjustment. This is slow, tedious, and highly inefficient.
Mocking requests: Manually crafting curl requests or using tools like Postman to simulate the webhook. This is useful but doesn't fully replicate the behavior of the actual service, which might have specific headers or payload structures.

Neither of these is ideal for rapid development and debugging. You need a way for the real, live webhook to reach your local machine.

Introducing Tunnelmole: Your Local Dev Environment's Public URL

This is where a tunneling service becomes an indispensable tool for the modern developer. Tunnelmole is a lightweight, command-line tool that creates a secure connection—a tunnel—between a public, internet-accessible URL and your local web server.

It's open source, easy to install, and requires just one simple command to get started. By using Tunnelmole, you can give a service like Zapier a real, public HTTPS URL that forwards all requests directly to your local WordPress instance.

How to Install and Use Tunnelmole

Installation is straightforward. For Linux, macOS, or Windows Subsystem for Linux (WSL), you can run a single command in your terminal:

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

This script handles the detection of your OS and installs the correct binary. For Windows users, you can download the tmole.exe executable and add it to your system's PATH.

Once installed, using it is even simpler. If your local WordPress site is running on port 8000, just run:

tmole 8000

Tunnelmole will spring into action and provide you with a public URL:

$ tmole 8000
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:8000
http://cqcu2t-ip-49-185-26-79.tunnelmole.net ⟶ http://localhost:8000

Now, you can use the https URL (https://cqcu2t-ip-49-185-26-79.tunnelmole.net in this example) as the webhook endpoint in any third-party service. When that service sends a webhook, it will travel through the Tunnelmole service directly to your local WordPress site.

How Tunnelmole Works

The concept behind Tunnelmole is elegant and effective. The client on your machine establishes a persistent and secure WebSocket connection to the public Tunnelmole service. When an incoming HTTP request hits your public URL, the Tunnelmole service forwards that request down the tunnel to the client, which then passes it on to your local server (e.g., your WordPress instance). The response from your local server travels back the same way.

Why Open Source Matters

Tunnelmole is fully open source, which provides several key advantages for developers:

Transparency: You can inspect the code for both the client and the server to understand exactly how it works and verify its security.
Control: While you can use the managed Tunnelmole service for free, you also have the option to self-host the server component. This gives you complete control over your tunneling infrastructure, which can be critical for organizations with strict security or privacy requirements.
Community: Being open source fosters a community of users who can contribute to the project, report issues, and help each other.

Step-by-Step: Creating a Custom WP Webhook Listener

Now, let's get our hands dirty and build a custom WordPress plugin to listen for an incoming webhook. In this example, we'll create an endpoint that accepts a POST request with a title and content and uses that data to create a new draft post.

Step 1: Set up a Basic Custom Plugin

First, create a new folder in your wp-content/plugins directory called my-webhook-listener. Inside that folder, create a PHP file with the same name: my-webhook-listener.php.

Add the standard plugin header to this file:

<?php
/**
 * Plugin Name:       My Webhook Listener
 * Description:       A simple plugin to listen for incoming webhooks and create a draft post.
 * Version:           1.0
 * Author:            Your Name
 */

// If this file is called directly, abort.
if (!defined('WPINC')) {
    die;
}

// All our code will go here.

Step 2: Registering a Custom API Endpoint

WordPress comes with a powerful REST API. We can extend it by registering our own custom route. This route will serve as the URL for our webhook.

We'll use the register_rest_route function, hooked into the rest_api_init action. Add this code to your plugin file:

add_action('rest_api_init', function () {
    register_rest_route('myplugin/v1', '/webhook', array(
        'methods' => 'POST',
        'callback' => 'my_webhook_callback',
        'permission_callback' => '__return_true' // WARNING: For testing only. Make this secure in production.
    ));
});

Let's break this down:

myplugin/v1: This is the namespace for our custom endpoints. It helps avoid conflicts with other plugins.
/webhook: This is the endpoint itself. The full URL will be https://your-site.com/wp-json/myplugin/v1/webhook.
'methods' => 'POST': We specify that this endpoint only accepts POST requests, which is standard for webhooks that send data.
'callback' => 'my_webhook_callback': This tells WordPress to execute the my_webhook_callback function when a request hits this endpoint.
'permission_callback' => '__return_true': This makes the endpoint public and accessible to anyone. This is great for simple testing but is a major security risk for a live site. We will discuss how to secure this later.

Step 3: Writing the Webhook Callback Function

Now, we need to create the my_webhook_callback function that does the actual work. This function will receive the incoming request data, sanitize it, and create a new post.

function my_webhook_callback(WP_REST_Request $request) {
    // Get the JSON payload from the request body
    $params = $request->get_json_params();

    // Sanitize and validate the incoming data
    $post_title = isset($params['title']) ? sanitize_text_field($params['title']) : 'Webhook Draft';
    $post_content = isset($params['content']) ? sanitize_textarea_field($params['content']) : 'No content provided.';

    // Create the post array
    $new_post = array(
        'post_title'    => $post_title,
        'post_content'  => $post_content,
        'post_status'   => 'draft', // Create it as a draft
        'post_author'   => 1, // Assign to the admin user
    );

    // Insert the post into the database
    $post_id = wp_insert_post($new_post);

    // Check for errors
    if (is_wp_error($post_id)) {
        return new WP_Error('post_creation_failed', 'Failed to create the post.', array('status' => 500));
    }

    // Return a success response
    $response_data = array(
        'success' => true,
        'message' => 'Post created successfully.',
        'post_id' => $post_id
    );

    return new WP_REST_Response($response_data, 200);
}

Step 4: Testing the Webhook with Tunnelmole

Now for the magic moment. Let's test our entire setup.

Activate the Plugin: Go to your local WordPress admin dashboard, navigate to "Plugins", and activate your "My Webhook Listener" plugin.
Start Tunnelmole: In your terminal, start Tunnelmole and point it to your local WordPress port. For example, if your site is at http://localhost:8080, run tmole 8080. Copy the public https URL it gives you.
Send the Webhook Request: Use a tool like curl or Postman to send a POST request to your new public endpoint.

Here is the curl command. Replace the placeholder URL with your actual Tunnelmole URL:

curl -X POST YOUR_TUNNELMOLE_URL_HERE/wp-json/myplugin/v1/webhook \
-H "Content-Type: application/json" \
-d '{
    "title": "New Post from Webhook",
    "content": "This content was sent automatically via a webhook!"
}'

Verify the Result: If everything worked, you should see the JSON success response in your terminal. Now, go to your WordPress admin dashboard, click on "Posts," and you should see a new draft titled "New Post from Webhook."

Congratulations! You have successfully created and tested a custom WP Webhook on your local machine.

Securing Your WP Webhooks

Remember that permission_callback we set to __return_true? It's time to fix that. An unprotected webhook endpoint is a gateway for spam and malicious attacks. Here are the primary methods for securing it.

Method 1: Using a Secret Key

The simplest approach is to require a secret key or token in the request. The webhook provider sends the secret, and your callback function checks for it.

Modify your register_rest_route call to use a custom permission callback:

'permission_callback' => 'my_webhook_permission_callback'

And then define the permission function:

function my_webhook_permission_callback(WP_REST_Request $request) {
    // Define your secret key. Store this securely, e.g., in wp-config.php
    define('MY_WEBHOOK_SECRET', 'a-very-long-and-random-secret-string');

    $auth_header = $request->get_header('Authorization');

    // Check if the header matches "Bearer <your_secret>"
    if ($auth_header && $auth_header === 'Bearer ' . MY_WEBHOOK_SECRET) {
        return true;
    }

    return new WP_Error('rest_forbidden', 'Invalid secret key.', array('status' => 403));
}

Now, the webhook provider must include an Authorization header with the value Bearer a-very-long-and-random-secret-string in its request.

Method 2: HMAC Signature Verification

A more robust method, used by services like Stripe and GitHub, is HMAC signature verification.

The provider and your plugin share a secret key.
When sending a webhook, the provider creates a cryptographic signature (a hash) of the request payload using the secret key.
This signature is sent as an HTTP header (e.g., X-Hub-Signature-256).
Your callback function independently generates its own signature of the received payload using the same secret key.
If your generated signature matches the one in the header, you know the request is authentic and its payload hasn't been tampered with.

Here is a conceptual example of the verification logic:

function verify_webhook_signature(WP_REST_Request $request) {
    $expected_signature = $request->get_header('X-Hub-Signature-256');
    $payload_body = $request->get_body();
    $secret = 'your-shared-secret';

    if (empty($expected_signature)) {
        return false;
    }

    // The signature from GitHub is prefixed with "sha256="
    list($algo, $hash) = explode('=', $expected_signature, 2);

    // Calculate our own hash
    $calculated_hash = hash_hmac($algo, $payload_body, $secret);

    // Compare them securely
    return hash_equals($hash, $calculated_hash);
}

Popular Plugins for WP Webhooks

If you don't want to code a custom solution, several powerful plugins in the WordPress ecosystem can manage webhooks for you. These are excellent for site owners or developers who need a quick, UI-driven solution.

WP Webhooks: A dedicated plugin that makes it easy to both send and receive webhooks. It integrates with many popular WordPress plugins and allows you to create automations directly from the admin dashboard.
Uncanny Automator: A comprehensive automation plugin, often described as "Zapier for WordPress." It connects various plugins and external apps using a system of triggers and actions, with webhooks being a core component.

These tools are great alternatives if your needs align with their feature sets and you prefer a no-code or low-code approach.

Conclusion

WP Webhooks are a transformative feature for any WordPress site, turning it from a simple content management system into a dynamic, interconnected hub. They are the key to unlocking powerful automations, achieving real-time data synchronization, and building modern, integrated web experiences.

While developing and testing webhooks has historically been a challenge due to the local-to-public communication barrier, open-source tools like Tunnelmole have completely streamlined the process. With a single command, you can give your local WordPress site a public URL, enabling you to receive and debug live webhook requests in real-time. This dramatically accelerates the development cycle and eliminates the friction of traditional testing methods.

By combining the flexibility of the WordPress REST API with the convenience of Tunnelmole, you have everything you need to build, test, and deploy robust and secure webhook integrations. Start automating your WordPress workflows today and unlock the true potential of your website.

How to Get a Webhook Online: A Developer's Guide

Robbie Cahill — Sun, 31 Aug 2025 01:18:54 +0000

Introduction to Online Webhooks

In modern web development, services frequently need to communicate with each other in real-time. While APIs allow your application to request data from other services, webhooks reverse this flow, enabling services to send data to your application as events happen. Whether it's a payment confirmation from Stripe, a new commit notification from GitHub, or a custom event from an IoT device, webhooks are the engine of the event-driven web.

However, there's a fundamental challenge developers face when working with webhooks: the service sending the webhook needs to reach your application over the internet. This means your application must have a public, "online" URL. During development, your application is typically running on localhost, a private address accessible only from your own computer.

So, how do you get your localhost server online to receive and test webhooks?

This guide will walk you through what it means for a webhook to be "online," why localhost isn't enough, and how you can use Tunnelmole, an open-source tool, to create a secure, public URL for your local development environment. By the end, you'll be able to receive, test, and debug webhooks directly on your machine, dramatically speeding up your development workflow.

What Exactly is a Webhook? The "Reverse API" Explained

If you're new to the concept, the easiest way to understand a webhook is to think of it as a "reverse API."

With a standard API, you (the client) initiate a request to a server to get or send data. For example, you might make a GET request to https://api.weather.com/latest to fetch the current weather. You are in control of when the request is made.
With a webhook, the roles are flipped. The external service (the webhook provider) initiates a request to your application's endpoint whenever a specific event occurs. You don't ask for the data; the provider pushes it to you.

This push model is incredibly efficient. Your application doesn't need to constantly poll an API endpoint asking, "Has anything new happened yet?" This saves network bandwidth, reduces server load for both you and the provider, and provides data in near real-time.

Common Use Cases for Webhooks

You'll find webhooks used in countless scenarios across the web:

Payment Gateways (Stripe, PayPal): Receive instant notifications for successful payments, failed transactions, or new subscriptions.
Version Control (GitHub, GitLab): Trigger CI/CD pipelines automatically when code is pushed to a repository.
Communication Platforms (Slack, Twilio): Build bots that react to messages or receive notifications about incoming calls and SMS messages.
eCommerce (Shopify): Update inventory systems or notify shipping departments when a new order is placed.
Automation Services (IFTTT, Zapier): Connect different apps and services to create powerful, automated workflows.

In all these cases, the provider needs a stable, public URL—a "webhook online" endpoint—to send its HTTP POST requests to.

The `localhost` Problem: Why Your Dev Server Isn't Online

When you're building a web application, you typically run it on your local machine. You might start a Node.js server that listens on http://localhost:3000 or a Python server on http://127.0.0.1:8000. These addresses are special; they point back to your own computer. This is perfect for development because it's fast, secure, and doesn't require an internet connection.

However, from the perspective of an external service like Shopify or GitHub, localhost is meaningless. When Shopify tries to send a webhook to http://localhost:3000/shopify-webhooks, its servers will try to connect to their own localhost, not yours.

Your development machine is usually sitting behind multiple layers of networking, including:

Network Address Translation (NAT): Your home or office router uses NAT to manage multiple devices on a private network with a single public IP address. It doesn't know which device to send an unsolicited incoming request to.
Firewalls: Your operating system and network router have firewalls that are configured by default to block almost all incoming connections for security reasons.

To make your local server accessible, you would traditionally have to deploy your code to a public server or configure complex network settings like port forwarding. This is slow, tedious, and a major roadblock to efficient development.

Solution: Get Your Webhook Online in Minutes with Tunnelmole

This is where a tunneling tool like Tunnelmole comes in. Tunnelmole is a simple, open-source command-line tool that creates a a secure tunnel from a public URL on the internet directly to your localhost server. It bridges the gap between the public internet and your private development environment, effectively putting your webhook endpoint "online."

Let's walk through the process step-by-step.

Step 1: Create a Basic Webhook Listener in Node.js

First, you need an application to receive the webhook. Let's create a very simple one using Express.js, a popular Node.js framework. If you don't have a Node.js project, create one:

mkdir webhook-listener
cd webhook-listener
npm init -y
npm install express

Now, create a file named index.js and add the following code:

const express = require('express');
const app = express();
const port = 3000;

// Middleware to parse JSON bodies. Most webhooks send data in JSON format.
app.use(express.json());

// Define our webhook endpoint
app.post('/webhook-handler', (request, response) => {
    console.log('🎉 Webhook Received!');

    // The data sent by the provider is in the request body
    const { body, headers } = request;
    console.log('Headers:', JSON.stringify(headers, null, 2));
    console.log('Body:', JSON.stringify(body, null, 2));

    // It's crucial to send a 200 OK response quickly
    // to let the provider know you've received the webhook.
    response.status(200).send('Webhook received successfully.');
});

app.listen(port, () => {
    console.log(`Webhook listener started on http://localhost:${port}`);
});

This code does three key things:

It starts a web server on localhost, port 3000.
It uses express.json() middleware to automatically parse incoming JSON payloads.
It defines an endpoint at /webhook-handler that listens for POST requests, logs the received data, and sends back a 200 OK status.

Run the application:

node index.js

You'll see the message: Webhook listener started on http://localhost:3000. Your server is running, but it's not yet online.

Step 2: Install Tunnelmole

Next, install Tunnelmole. It's a native NodeJS application and can be installed via NPM or a simple script.

For Linux, macOS, or Windows Subsystem for Linux (WSL):
The easiest way is to run the installation script.

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

Using NPM (requires Node.js):
If you have Node.js installed, you can use npm.

sudo npm install -g tunnelmole

For Windows:
Download tmole.exe and place it in a folder that's included in your system's PATH.

Step 3: Launch Tunnelmole to Go Online

With your Node.js server running in one terminal, open a new terminal and run Tunnelmole. Point it to the port your application is listening on (in our case, 3000).

tmole 3000

Tunnelmole will connect to its service and generate a public URL. The output will look something like this:

Your Tunnelmole Public URLs are below and are accessible internet wide. Always use HTTPs for the best security

https://k8sjer-ip-12-34-56-78.tunnelmole.net ⟶ http://localhost:3000
http://k8sjer-ip-12-34-56-78.tunnelmole.net ⟶ http://localhost:3000

That's it! The HTTPS URL is now your public webhook endpoint. You can now use this URL in any webhook provider's settings. For our example, the full URL would be:

https://k8sjer-ip-12-34-56-78.tunnelmole.net/webhook-handler

Any request sent to this URL will be securely tunneled to your Express app running on localhost:3000.

How Tunnelmole Makes Your Webhook Online

Tunnelmole's architecture is designed to be simple and effective. The diagram below illustrates how it works:

Client Connection: The tmole client on your machine establishes a persistent, outbound connection to the Tunnelmole service running on a public server. This connection is typically a WebSocket, which works even behind most firewalls and NATs because it's initiated from inside your network.
Public URL Generation: The Tunnelmole service assigns a unique public URL (e.g., https://k8sjer-....tunnelmole.net) and associates it with your client's connection.
Incoming Webhook: When a webhook provider (like GitHub) sends a request to your public URL, the request first hits the Tunnelmole service.
Tunneling: The service immediately forwards the entire HTTP request (headers, body, and all) through the established tunnel to the Tunnelmole client on your machine.
Local Forwarding: The client receives the request and forwards it to your local server (e.g., http://localhost:3000).
Response Path: Your local server processes the request and sends a response (e.g., a 200 OK). This response travels back through the exact same path: from your server to the tmole client, through the tunnel to the service, and finally back to the original webhook provider.

This entire process happens in seconds, allowing for a seamless, real-time development experience.

Open Source and Self-Hosting: Taking Full Control

One of the most significant advantages of Tunnelmole is that it's fully open source. Both the client you run locally and the server that manages the tunnels are available on GitHub. This provides several key benefits:

Transparency and Security: You can audit the code yourself to understand exactly what it's doing. There are no black boxes. For teams working in high-security environments, this is a non-negotiable feature.
Customization: If you need specific features or integrations, you can fork the project and modify it to suit your needs.
Self-Hosting: While Tunnelmole offers a convenient hosted service, you are not locked into it. You can deploy the Tunnelmole service on your own infrastructure (e.g., AWS, a VPS, or even a Raspberry Pi). Self-hosting gives you complete control over your data privacy, domain names, and operational stability. You can use custom subdomains without a subscription.

The Ultimate Workflow: Debugging Webhooks with Breakpoints

The ability to get a webhook online and route it to your local machine enables the most powerful debugging technique of all: breakpoints.

Instead of adding endless console.log statements, you can set a breakpoint in your IDE (like Visual Studio Code) right inside your webhook handler function.

Set a breakpoint on the first line inside your /webhook-handler in index.js.
Start your application in debug mode in your IDE.
Trigger a webhook from your provider (e.g., by making a push in GitHub or using a tool like Postman to send a request to your Tunnelmole URL).

When the webhook is sent, the execution of your code will pause at the breakpoint. From there, you can:

Inspect the entire request payload: View the webhook body and headers in their raw, unprocessed form.
Step through your code: Execute your logic line-by-line to see how it behaves.
Check variable states: Examine the values of variables at any point in the process.
Identify errors instantly: See exactly where your code fails or behaves unexpectedly.

This level of interactive, real-time debugging is impossible if you have to deploy your code to a remote server for every change. It transforms webhook development from a frustrating guessing game into a streamlined, efficient process.

Conclusion

Understanding how to get a webhook "online" is a critical skill for any modern developer. While the complexities of internet networking can make it seem daunting, tools like Tunnelmole abstract away the difficulty, allowing you to focus on what matters: building and testing your application's logic.

By creating a secure tunnel from a public URL to your localhost server, Tunnelmole enables you to:

Receive and test webhooks from any provider directly on your development machine.
Debug your code interactively with breakpoints for a fast and efficient workflow.
Share your work with colleagues or clients before its deployed.
Leverage an open-source tool that you can audit, customize, and even self-host for maximum control.

The next time you're tasked with integrating a webhook, you'll know exactly how to bring it online to your local environment, saving you hours of time and frustration.

Notion Webhooks: A Complete Guide for Developers (2025)

Robbie Cahill — Sun, 31 Aug 2025 01:17:16 +0000

Notion has become a powerhouse for personal and collaborative productivity, but its true potential is unlocked when you start automating it. For developers, this often means working with webhooks. While Notion doesn't have traditional, one-click outgoing webhooks like GitHub or Slack, its powerful API allows you to create robust, webhook-like integrations.

This guide will walk you through the entire process of setting up a "Notion webhook" system. You'll learn how to build a listener service with Node.js and Express, expose it to the internet for testing and development with the open source Tunnelmole tunneling tool, and create a workflow that effectively gives you real-time notifications for changes in your Notion database.

By the end of this tutorial, you'll have a fully functional webhook endpoint that can receive and process data triggered by events in your Notion workspace.

What are Webhooks?

Before diving into the specifics of Notion, let's quickly recap what a webhook is.

In a typical API interaction, your application (the client) sends a request to a server, and the server sends a response. You are initiating the communication.

Webhooks flip this model on its head. They are automated, server-to-server messages sent when a specific event occurs. Instead of your application polling for changes, the service (the "webhook provider") sends a POST request to a public URL you provide—your "webhook listener." This is often called a "reverse API" because it's the server that initiates the request.

This event-driven approach is far more efficient than constant polling, saving resources and providing near real-time data.

How "Notion Webhooks" Work

As of 2025, Notion's API does not support native outgoing webhooks. You can't simply go into a Notion database, click "Add Webhook," and paste your URL.

So, how do we create a "Notion webhook"? We use a simple, powerful pattern:

Polling Service: An intermediary service monitors your Notion database for changes. This can be a third-party automation platform like Zapier or Make, or a custom script running on a schedule (e.g., a cron job).
Webhook Trigger: When this service detects a change (like a new page being added or a property being updated), it triggers an action.
HTTP Request: That action is to send an HTTP POST request to a public URL that you control. This is your webhook endpoint.
Local Webhook Handler: Your local application receives this request and processes the payload, which contains the data from the Notion event.

To make this work during development, your local server (running on localhost) needs a public URL. This is where a tunneling tool becomes essential.

Prerequisites

To follow this guide, you will need:

A Notion Account and a workspace.
Node.js (v16.10 or later) and npm installed on your machine.
Basic understanding of JavaScript and the Express.js framework.
A code editor like VS Code.

Step 1: Set Up Your Node.js Webhook Handler

First, let's build a simple Express.js application that will act as our webhook listener. This server will have one job: to listen for incoming POST requests on a specific endpoint.

Create a new directory for your project and initialize it with npm.

mkdir notion-webhook-handler
cd notion-webhook-handler
npm init -y

Next, install Express and body-parser, which helps parse the incoming request body.

npm install express body-parser

Now, create a file named index.js and add the following code:

const express = require('express');
const bodyParser = require('body-parser');

const app = express();
const port = 3000;

// Use body-parser middleware to parse JSON request bodies
app.use(bodyParser.json());

// Define the webhook endpoint
app.post('/notion-webhook', (req, res) => {
    console.log('🎉 Webhook received!');

    // The data from Notion (sent by the intermediary) will be in the request body
    const { body } = req;
    console.log('Payload:');
    console.log(JSON.stringify(body, null, 2));

    // Acknowledge receipt of the webhook
    res.status(200).send('Webhook received successfully.');
});

// A root endpoint to confirm the server is running
app.get('/', (req, res) => {
    res.send('Notion Webhook Handler is running!');
});

app.listen(port, () => {
    console.log(`Server listening at http://localhost:${port}`);
});

This code sets up a simple web server with two routes:

GET /: A simple health check to confirm the server is running.
POST /notion-webhook: This is our main webhook endpoint. It logs the received payload to the console and sends a 200 OK response.

Run the server to make sure everything is working:

node index.js

You should see Server listening at http://localhost:3000 in your terminal. You can open http://localhost:3000 in your browser to see the "Webhook Handler is running!" message.

Step 2: Get a Public URL with Tunnelmole

Your Express server is running on localhost, which is only accessible from your own computer. For an external service to send it a webhook, you need a publicly accessible HTTPS URL. This is where Tunnelmole comes in.

Tunnelmole is an open-source tool that creates a secure tunnel between a public URL and your local development environment. It's incredibly simple to use and you can be up and running in seconds.

Install Tunnelmole

You can install Tunnelmole using npm if you have Node.js installed:

sudo npm install -g tunnelmole

Alternatively, for Linux, Mac, or WSL, you can use the following curl command:

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

Run Tunnelmole

With your Node.js server still running, open a new terminal window and run the following command to tunnel port 3000:

tmole 3000

Tunnelmole will start and display a public URL that now points to your local server.

$ tmole 3000
Your Tunnelmole Public URLs are below and are accessible internet wide. Always use HTTPs for the best security

https://k8sjer-ip-12-34-56-78.tunnelmole.net ⟶ http://localhost:3000
http://k8sjer-ip-12-34-56-78.tunnelmole.net ⟶ http://localhost:3000

Copy the https:// URL. This is your public webhook URL. Anyone on the internet can now send requests to this URL, and they will be forwarded securely to your Express app running on localhost:3000.

Keep Tunnelmole running in this terminal window.

How Tunnelmole Works

The magic of Tunnelmole lies in its simplicity. It establishes a persistent WebSocket connection from your machine to the Tunnelmole cloud service. When a request hits your public URL, the service relays it through this tunnel to your local machine, which then forwards it to your application.

A key benefit of Tunnelmole is that it's open source. Both the client and the server-side code are available for review. For ultimate control and privacy, you can even self-host the Tunnelmole service on your own server.

Step 3: Create a Notion Integration

To allow an application or service to access your Notion workspace, you need to create an "integration."

Go to the Integrations Page: Navigate to www.notion.so/my-integrations.
Create a New Integration: Click the + New integration button.
Fill in the Details:
- Name: Give it a descriptive name, like "My Database Webhook".
- Associated workspace: Select your workspace.
- Capabilities: For this example, "Read content" is sufficient.
- Click Submit.
Copy the Secret Token: On the next screen, you'll see your "Internal Integration Token." Click "Show" and copy this token. Treat it like a password; don't expose it in public code repositories.

Step 4: Create and Share a Notion Database

Now, let's create the Notion database that our integration will monitor.

Create a new page in your Notion workspace.
On the new page, select /table and choose Table - Full page.
Give your database a name, like "My Webhook-Enabled Tasks."
Share the database with your integration:
- Click the ••• menu in the top-right corner of the database page.
- Click + Add connections.
- Search for the integration you just created (e.g., "My Database Webhook") and select it.
- Confirm the connection.

Step 5: Configure an Automation to Trigger the Webhook

As mentioned, we need an intermediary to watch for changes and call our webhook. For this tutorial, we'll use Zapier as an example, as it has a free tier that is perfect for this. The same principle applies to other services like Make (formerly Integromat) or Pipedream.

Sign up or log in to Zapier.
Click Create Zap.
Set up the Trigger:
- Search for and select Notion.
- For the Event, choose New Database Item.
- Connect your Notion account, authorizing Zapier to use the integration you created.
- Select the Database you just created ("My Webhook-Enabled Tasks").
- Click Test trigger. Zapier will try to find a recent item in your database. Go ahead and add a new row to your Notion table so Zapier has something to find.
Set up the Action:
- After the trigger test is successful, add a new action step.
- Search for and select Webhooks by Zapier.
- For the Event, choose POST.
- Now, configure the request:
  - URL: Paste your public Tunnelmole URL here, followed by the endpoint path. For example: https://k8sjer-ip-12-34-56-78.tunnelmole.net/notion-webhook.
  - Payload Type: Set this to Json.
  - Data: This is where you map the data from Notion. You can create a JSON object and pull in fields from the Notion database item. For example:
    - name: Map this to the Name property from Notion.
    - status: Map this to the Status property.
    - url: Map this to the URL of the Notion page.
  - Headers: Leave this blank for now, but you could add an authentication token here for security.
Test and Publish:
- Click Test step. Zapier will send a real POST request to your Tunnelmole URL.
- Look at your Node.js server's terminal. You should see the "🎉 Webhook received!" message and the full JSON payload from Zapier printed to the console!
```
{
  "name": "My First Task",
  "status": "Not started",
  "url": "https://www.notion.so/..."
}
```

* If everything looks good, **Publish** your Zap.

Congratulations! You now have a live webhook integration. Every time you add a new item to your Notion database, Zapier will detect it and send its data to your local server via Tunnelmole.

Step 6: Secure Your Webhook Endpoint

Right now, your endpoint is public. Anyone who knows the URL can send data to it. In a production environment, you must verify that incoming requests are legitimate. A simple way to do this is with a shared secret token.

In Zapier: In the Headers section of your Webhooks action, add a new header.
- Key: X-Secret-Token
- Value: A long, random string. You can generate one easily.
In your Node.js app: Create a middleware function to check for this header before your main handler runs.

Update your index.js:

const express = require('express');
const bodyParser = require('body-parser');

const app = express();
const port = 3000;

// THIS IS YOUR SECRET. Store it securely, e.g., in an environment variable.
const SHARED_SECRET = 'your-super-secret-random-string';

app.use(bodyParser.json());

// Middleware to verify the secret token
const verifySecret = (req, res, next) => {
    const receivedSecret = req.get('X-Secret-Token');
    if (receivedSecret && receivedSecret === SHARED_SECRET) {
        // Secrets match, proceed to the handler
        next();
    } else {
        console.warn('⚠️ Unauthorized request: Invalid or missing secret token.');
        res.status(401).send('Unauthorized');
    }
};

// Apply the middleware ONLY to your webhook endpoint
app.post('/notion-webhook', verifySecret, (req, res) => {
    console.log('🎉 Webhook received (and authenticated)!');

    const { body } = req;
    console.log('Payload:');
    console.log(JSON.stringify(body, null, 2));

    res.status(200).send('Webhook received successfully.');
});

app.get('/', (req, res) => {
    res.send('Notion Webhook Handler is running!');
});

app.listen(port, () => {
    console.log(`Server listening at http://localhost:${port}`);
});

Restart your Node server (Ctrl+C then node index.js). Now, only requests from Zapier that include the correct secret token will be processed.

Conclusion and Next Steps

You've successfully built a complete, secure webhook integration for Notion from scratch. You learned how to:

Create a webhook listener with Node.js and Express.
Expose your local server to the internet using the open-source tool, Tunnelmole.
Configure a Notion integration and connect it to a database.
Use an automation service like Zapier to poll for changes and trigger your webhook.
Secure your endpoint with a shared secret.

This foundation opens up a world of automation possibilities. You could extend this application to:

Send a Slack message when a task is marked "Done."
Create a calendar event from a new entry in a Notion "Meetings" database.
Sync contacts between Notion and a CRM.
Log changes to an external audit file.

Happy automating!

How to Test n8n Webhooks Locally with Tunnelmole

Robbie Cahill — Sun, 31 Aug 2025 01:15:12 +0000

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:

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.
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.

Open your n8n canvas and create a new workflow.
Click the + button to add a new node.
Search for and select the "Webhook" trigger node.
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
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.
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.

Open a new terminal window (leave n8n running in its own).
Run the following command:
```
tmole 5678
```

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.

In your n8n canvas, click the "Execute Workflow" button. The Webhook node will now be listening for a test request.
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.
When you send this request, curl will receive the response you configured in the "Respond to Webhook" node:
```
{
  "status": "success",
  "message": "Webhook received!"
}
```
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!

DEV Community: Robbie Cahill

I Built a Localhost Tunneling tool in TypeScript - Here's What Surprised Me

1. The Dark Side: Phishing Scammers Love Tunneling Tools

Solution 1: The X-Forwarded-For Header

Solution 2: IP in the URL

2. Abstraction Disappointment: fetch Does Not Give You the Pure HTTP Request

3. You Can and Should Send Typed JSON as WebSocket Messages

4. Node.js Will Not Hold Your Hand: Memory Leaks Are a Thing

Conclusion

AI Agents Deleting Home Folders? Run Your Agent in Firejail and Stay Safe

Introduction: The Double-Edged Sword of AI Agents

What is Firejail and Why is it Effective?

Crafting a Secure Firejail Profile for VS Code

Deconstructing the Security Profile

Testing Your Sandbox: Trust, But Verify

Step 1: Create a "Canary" File

Step 2: Launch VS Code Inside Firejail

Step 3: Instruct the AI Agent to Breach the Walls

Step 4: Analyze the (Successful) Failure

Conclusion: Develop Powerfully, and Safely

6 Ways A Node Developer Can Drastically Boost Their Productivity in 2025

Introduction

1. Master the Fuzzy Finder in Your IDE

2. Use a Real Debugger Instead of console.log()

3. Embrace async/await and Banish "Callback Hell"

4. Share Your Work Quickly with a Public URL

5. Automate Repetitive Tasks with npm Scripts

6. Get Fast Feedback with nodemon

Conclusion

Airtable Webhook Integration: A Developer's Guide

Introduction

What are Airtable Webhooks?

Why You Need a Public URL for Local Development

Setting Up Your Local Webhook Receiver (Node.js & Express)

Prerequisites

Step 1: Initialize Your Project

Step 2: Install Express

Step 3: Create the Server Code

Step 4: Run Your Server

Exposing Your Local Server with Tunnelmole

Install Tunnelmole

Run Tunnelmole

How Tunnelmole Works

Configuring the Airtable Automation

Testing End-to-End

Securing Your Webhook

Conclusion

Tunnelmole Features

How to Use Google Chat Webhooks: A Complete Guide

Part 1: Incoming Webhooks - Pushing Messages to Google Chat

Creating an Incoming Webhook in Google Chat

Sending Your First Message with curl

Crafting Rich Messages with Cards

Example: Sending a Google Chat Message with Node.js

Part 2: Outgoing Webhooks - Building Interactive Chat Apps

The Challenge: Developing Locally

The Solution: Tunnelmole for a Public URL

Building an Interactive Google Chat App with Node.js and Tunnelmole

Step 1: Create the Express.js App

Step 2: Install and Run Tunnelmole

Step 3: Configure Your App in the Google Cloud Console

Conclusion

Shopify Webhooks: The Complete Guide for Developers

What are Shopify Webhooks?

Common Use Cases for Shopify Webhooks

The Challenge: Testing Webhooks on Localhost

The Solution: Tunnelmole for Effortless Local Development

Step-by-Step: Testing Shopify Webhooks with Node.js and Tunnelmole

Prerequisites

Step 1: Create a Basic Express.js Server

Step 2: Install and Run Tunnelmole

Step 3: Create the Webhook in Shopify

Step 4: Trigger a Test Webhook

Securing Your Shopify Webhook: Signature Verification

Step 1: Update Your Server for HMAC Verification

Step 2: Get Your Webhook Secret Key

Production Best Practices

Conclusion

GitHub Webhook: A Complete Guide to Automation

What Exactly is a Webhook?

Solution 1: The `X-Forwarded-For` Header

2. Abstraction Disappointment: `fetch` Does Not Give You the Pure HTTP Request

2. Use a Real Debugger Instead of `console.log()`

3. Embrace `async/await` and Banish "Callback Hell"

5. Automate Repetitive Tasks with `npm` Scripts

6. Get Fast Feedback with `nodemon`

Sending Your First Message with `curl`

The `localhost` Problem: Why Your Dev Server Isn't Online