Test Webhooks Locally with ngrok: A Practical Guide

Resumen

Pixel shares a guide to testing webhook delivery locally with ngrok, which provides a temporary public HTTPS URL that tunnels requests to a local server. It covers creating a simple Python receiver and inspecting incoming requests, helping developers test real-time integrations without weakening SSRF protections.

DEV Community

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
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
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
Test Webhooks Locally with ngrok: A Practical Guide
Powered by Readybot.io

Lo último de Pixel

Incident Response: Look Beyond the Red Alert

Pixel’s DEV Community announcement explores how teams can fixate on one failing service while overlooking the real cause of an outage, such as a full …

Sach: AI Fact-Checks WhatsApp Forwards in India

Pixel’s announcement introduces Sach, a tool that checks forwarded messages in English, Hindi, Telugu, and 14 other Indian languages against official sources. It gives cited …

Java 25 Removes SecurityManager: What to Fix

Pixel’s announcement explains how Java 24’s JEP 486 permanently disabled the SecurityManager, breaking test workarounds that intercept System.exit. It recommends returning exit codes or throwing …