Test Stripe, GitHub and PayPal Webhooks on Localhost with a TLS Tunnel

Why Localhost Webhook Testing Breaks

Webhooks are HTTP POST requests that an external service fires at your server when an event occurs a payment succeeds, a pull request is merged, a subscription lapses. The problem is that your development server runs on 127.0.0.1, which is only reachable from your own machine. Stripe cannot route to it. GitHub cannot either.

Port forwarding is the classic workaround, but most ISPs now deploy CGNAT your router doesn't own a public IP, a carrier NAT does. Even when port forwarding works, you still deal with dynamic IPs, firewall rules, and the fact that every teammate needs their own setup from scratch.

A TLS tunnel solves all of this. It creates an outbound connection from your machine to a relay server that owns a public HTTPS URL. Stripe posts to that URL. The relay forwards the request through the tunnel to your local port. No inbound ports need to be open.

What Is a TLS Tunnel?

A TLS tunnel is a tunnel type where the relay terminates TLS at the edge and forwards decrypted traffic to your local process. The relay presents a trusted certificate to Stripe. Stripe delivers the POST over HTTPS. Your local Node.js, Python, or Laravel app receives a plain HTTP request on localhost:3000 no certificate configuration required on your end.

Localtonet supports HTTP, HTTPS, TCP, UDP, and TLS tunnels. The TLS type handles certificate management automatically. You don't provision a cert or configure an ACME client. You get a stable subdomain that persists across agent restarts on paid plans, so you register your webhook URL once and never update it.

Step-by-Step Setup with Localtonet

chmod +x localtonet
./localtonet authtoken YOUR_TOKEN_HERE

.\localtonet.exe authtoken YOUR_TOKEN_HERE

curl -I https://yourname.localto.net

Configuring Stripe Webhooks

In the Stripe Dashboard, go to Developers → Webhooks → Add endpoint. Paste your Localtonet HTTPS URL and append your webhook handler path:

https://yourname.localto.net/webhooks/stripe

Select the events you care about payment_intent.succeeded, customer.subscription.deleted, and so on then click Add endpoint. Stripe immediately sends a test event. Check your local server logs to confirm receipt.

Always validate the Stripe-Signature header in your handler. Stripe signs every event with your endpoint's secret, visible in the webhook dashboard after creation.

const sig = req.headers['stripe-signature'];
const event = stripe.webhooks.constructEvent(
  req.body,         // must be raw Buffer, not parsed JSON
  sig,
  'whsec_YOUR_ENDPOINT_SECRET'
);

Configuring GitHub Webhooks

In your GitHub repository, go to Settings → Webhooks → Add webhook. Set the Payload URL to your tunnel URL with your handler path, set Content type to application/json, and choose a secret.

https://yourname.localto.net/webhooks/github

GitHub sends a ping event immediately on creation. If your local server returns 200, the webhook is working. Validate every incoming request against the HMAC-SHA256 signature in the X-Hub-Signature-256 header.

import hmac, hashlib

sig = request.headers.get('X-Hub-Signature-256', '')
expected = 'sha256=' + hmac.new(
    SECRET.encode(), request.data, hashlib.sha256
).hexdigest()

if not hmac.compare_digest(sig, expected):
    return 'Unauthorized', 401

Configuring PayPal IPN and Webhooks

PayPal offers two notification systems: the legacy IPN and the newer Webhooks API available under REST apps. Both require a publicly reachable HTTPS URL exactly what your Localtonet tunnel provides.

For Webhooks (REST): log into the PayPal Developer Dashboard, open your app, and add a webhook URL pointing at your tunnel. For IPN: in your PayPal sandbox account go to Profile → My Selling Tools → Instant Payment Notifications and paste the URL.

https://yourname.localto.net/webhooks/paypal

// Webhook routes — raw Buffer, not parsed JSON
app.use('/webhooks/stripe', express.raw({ type: 'application/json' }));

// All other routes — normal JSON parsing
app.use(express.json());

Tips for Webhook Debugging

Frequently Asked Questions