How to Test GitHub Webhooks Locally Without Port Forwarding

Testing webhooks locally is one of those problems that sounds simple until you actually try it. Your GitHub webhook needs a publicly routable URL, but your development machine is behind a NAT or firewall. You can't just point GitHub at http://localhost:3000/webhook—GitHub's servers can't reach it.

This article covers the real approaches developers use to test GitHub webhooks locally, their trade-offs, and when to reach for each one.

The Core Problem

GitHub webhooks work by making HTTP POST requests to a URL you specify. That URL must be publicly accessible over the internet. Your local machine typically isn't. You have a few options:

1. Deploy to staging – reliable but slow feedback loop
2. Port forward or expose your machine – security risk, fragile
3. Use a tunneling service – works well, but adds complexity
4. Use a webhook relay/inspector – captures and forwards events

Let's walk through each approach with real code.

Option 1: ngrok (The Classic)

ngrok creates a tunnel from a public URL to your localhost. It's been the go-to for years.

Setup:

# Install ngrok
brew install ngrok  # macOS
# or download from https://ngrok.com

# Start your Express webhook handler
node webhook-server.js

# In another terminal, expose port 3000
ngrok http 3000

ngrok gives you a URL like https://abc123.ngrok.io. You paste that into GitHub's webhook settings, and requests flow through.

Pros:

• Simple, well-documented
• Works with any HTTP service
• Free tier available
• ngrok web UI shows request/response history

Cons:

• URL changes on restart (free tier) unless you pay for a static domain
• Adds a hop; latency increases slightly
• ngrok session dies if your machine sleeps
• Free tier has bandwidth limits

Real webhook handler example:

const express = require('express');
const crypto = require('crypto');

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

const WEBHOOK_SECRET = process.env.GITHUB_WEBHOOK_SECRET;

// Middleware to verify GitHub's HMAC signature
function verifyGitHubSignature(req, res, next) {
  const signature = req.headers['x-hub-signature-256'];
  if (!signature) {
    return res.status(401).json({ error: 'Missing signature' });
  }

  const body = req.rawBody || JSON.stringify(req.body);
  const hash = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(body)
    .digest('hex');
  const expected = `sha256=${hash}`;

  if (!crypto.timingSafeEqual(signature, expected)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  next();
}

// Capture raw body for signature verification
app.use(express.raw({ type: 'application/json' }));
app.use((req, res, next) => {
  req.rawBody = req.body;
  req.body = JSON.parse(req.body);
  next();
});

app.post('/webhook', verifyGitHubSignature, (req, res) => {
  const event = req.headers['x-github-event'];
  const payload = req.body;

  console.log(`Received ${event} event`);
  console.log(`Repository: ${payload.repository?.full_name}`);
  console.log(`Action: ${payload.action}`);

  // Handle specific events
  if (event === 'push') {
    console.log(`Pushed ${payload.commits.length} commits to ${payload.ref}`);
  } else if (event === 'pull_request') {
    console.log(`PR ${payload.action}: ${payload.pull_request.title}`);
  }

  res.status(200).json({ received: true });
});

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

Option 2: Cloudflare Tunnel

Cloudflare Tunnel (formerly Argo Tunnel) is similar to ngrok but backed by Cloudflare's infrastructure.

Setup:

brew install cloudflare/cloudflare/cloudflared
cloudflared tunnel --url http://localhost:3000

You get a URL like https://abc123.trycloudflare.me.

Pros:

• Free, no bandwidth limits
• Stable URLs with a paid Cloudflare domain
• Lower latency (Cloudflare edge network)
• Works reliably

Cons:

• URL changes on restart (free tier)
• Requires Cloudflare account
• Less webhook-specific tooling than ngrok

Option 3: Webhook Inspector (Anonymily)

Instead of tunneling your entire machine, a webhook inspector captures events in the cloud and forwards them to your localhost over a persistent connection. This is different from tunneling.

How it works:

1. You get a stable public endpoint: https://api.anonymily.com/h/my-github-hook
2. You point GitHub at that URL
3. You run npx @anonymilyhq/cli listen 3000 on your machine
4. The CLI connects to Anonymily and listens for events
5. When GitHub posts to the endpoint, Anonymily captures it and forwards it to your localhost over Server-Sent Events
6. Your handler processes it normally

Setup:

# Terminal 1: Start your webhook handler (same code as above)
node webhook-server.js

# Terminal 2: Start the Anonymily listener
npx @anonymilyhq/cli listen 3000

# Output:
# ✓ Listening on https://api.anonymily.com/h/abc12345
# ✓ Forwarding to http://localhost:3000

Then paste https://api.anonymily.com/h/abc12345 into GitHub's webhook settings.

Pros:

• Stable endpoint that survives restarts
• Captures events even when localhost is down (replay later)
• Web UI shows full request/response history
• No port forwarding or machine exposure
• Free tier includes 200 requests per hook
• Pro tier ($9/month) adds modify-and-replay, signature verification helpers, and provider-signed synthetic test events

Cons:

• Adds a dependency (requires Anonymily account)
• Not suitable for production (use Hookdeck or Svix for that)
• Free tier limited to 48 hours of history

When to use it: You're iterating fast and want a stable endpoint that persists across restarts. You don't want to manage ngrok URLs or Cloudflare tunnels.

Option 4: Local Reverse Proxy (Advanced)

If you control your own domain and have a VPS, you can reverse-proxy requests to your local machine. This is more work but gives you full control.

# On your VPS, in nginx.conf
server {
    listen 443 ssl http2;
    server_name webhook.example.com;

    ssl_certificate /etc/letsencrypt/live/webhook.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/webhook.example.com/privkey.pem;

    location / {
        proxy_pass http://your-home-ip:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Pros:

• Full control, no third-party services
• Stable domain
• Works for any webhook provider

Cons:

• Requires a VPS and domain
• Security risk if your home IP is exposed
• More operational overhead
• Not practical for most developers

Comparing the Approaches

Best Practices

Always verify signatures. GitHub signs every webhook with an HMAC. Use the x-hub-signature-256 header to validate authenticity. The code example above shows how.

Log everything during development. Print the event type, payload, and any processing results. You'll debug faster.

Test with real events. Don't mock GitHub's payloads—use actual events from your test repository. Replay features in ngrok and Anonymily are invaluable here.

Handle idempotency. GitHub retries failed webhooks. Your handler should be idempotent (safe to call multiple times with the same data). Use a delivery ID or timestamp to deduplicate.

Set appropriate timeouts. GitHub waits 30 seconds for a response. If your handler takes longer, GitHub times out and retries. Keep webhook handlers fast.

Getting Started

For most developers, start with ngrok or a webhook inspector. ngrok is the most familiar; Anonymily is faster if you want a stable endpoint without managing URLs.

If you want to try a webhook inspector, run:

npx @anonymilyhq/cli listen 3000

Then visit https://anonymily.com to create an endpoint and see the web UI. It takes 30 seconds.

Choose the tool that fits your workflow. The important thing is testing webhooks locally before pushing to production.