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
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()
python3 webhook_receiver.py
2. Expose it with ngrok
brew install ngrok
ngrok config add-authtoken <your-token>
ngrok http 4000
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" }
}
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)
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.