DEV Community

Kaziu
Kaziu

Posted on

Testing Webhook Delivery by Temporarily Exposing Your Local Server with ngrok

Introduction

I'm building a webhook sending feature for a SaaS product.

Our customers sync data from the SaaS into their own core business systems, but right now they do it by polling the SaaS API (asking for changes at regular intervals), so updates don't show up in real time.
The goal is to send a webhook to the customer's system the moment data changes on the SaaS side, so their core system's data updates automatically.

The tricky part was how to set up the "receiving end" locally.

Users can enter any destination URL they like, so if someone specifies an address on an internal network, it opens the door to an SSRF (Server-Side Request Forgery) attack, where the server is tricked into sending requests to internal systems.
As a countermeasure, I added a restriction to only send to HTTPS URLs that are publicly reachable on the internet. That means even if I spin up a receiver on my own localhost, I can't send to it.

What is ngrok?

It's a tool that gives a server running on your own PC a temporary public URL.

External service ──→ https://xxxx.ngrok-free.app ──(relayed by ngrok)──→ localhost:3000 on your PC
Enter fullscreen mode Exit fullscreen mode

Since you get a public HTTPS URL, you can check delivery locally without loosening the SSRF checks.
While it's running, you can also inspect the contents of incoming requests at http://localhost:3040.

How to use it

1. Create a dummy receiver

A server that just accepts a POST, prints what it got, and returns 200.

# webhook_receiver.py
from http.server import BaseHTTPRequestHandler, HTTPServer
import json

class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        body = self.rfile.read(int(self.headers['Content-Length']))
        print(dict(self.headers))
        print(json.dumps(json.loads(body), indent=2, ensure_ascii=False))
        self.send_response(200)  # Change this to 500 or 401 to check how failures are handled
        self.end_headers()

HTTPServer(('0.0.0.0', 4000), Handler).serve_forever()
Enter fullscreen mode Exit fullscreen mode
python3 webhook_receiver.py
Enter fullscreen mode Exit fullscreen mode

2. Expose it with ngrok

brew install ngrok
ngrok config add-authtoken <your-token>
ngrok http 4000
Enter fullscreen mode Exit fullscreen mode

The https://xxxx.ngrok-free.app it displays is your public URL.

3. Set the URL on the sending side and try it

Put this URL into the app's webhook settings and update some data, and the received JSON shows up in the receiver's terminal.

{
  "eventId": "event_123",
  "type": "order",
  "occurredAt": "2026-01-01T12:00:00+09:00",
  "order": { "id": 1, "name": "Sample order" }
}
Enter fullscreen mode Exit fullscreen mode

Things to watch out for

  • The public URL is accessible to anyone, so shut it down as soon as you're done checking
  • Don't send real data; test with dummy data
  • Check the detailed cases (errors, timeouts, etc.) in automated tests by stubbing out HTTP, and use ngrok for the final end-to-end check

Summary

  • Polling isn't real-time, so I'm building webhooks that send changes immediately
  • The SSRF protection only allows sending to public URLs, but with ngrok you can test locally without loosening those checks

Top comments (1)

Collapse
 
krusenas profile image
Karolis •

Check what the ngrok free domain returns to clients that aren't browsers. It can hand back a 200 warning page unless you skip it first, and that looks like a dropped delivery in your logs. fwiw I'm the founder of Webhook Relay. It keeps failed deliveries and lets you replay them.