Test Webhooks Locally with a Public URL

Webhooks are awkward to develop against. The provider only POSTs to a public URL, so your local handler is invisible to it. The classic workarounds — deploying to a staging box for every code change, or replaying a payload you saved by hand — are slow and never quite match what the provider actually sends. The fix is to give your local handler a real public URL and a way to see and re-send what arrives.

Expose your local handler

Start your webhook receiver locally, then expose the port it listens on — the same one-command flow as exposing localhost to the internet:

# Your handler is listening on :3000
ngris http 3000 --url hooks.ngris.com

Paste that HTTPS URL into the provider's webhook settings. Using --url with a reserved hostname keeps the URL stable, so you register it once and it survives restarts. Drop the flag and you get an ephemeral hostname instead — fine for a throwaway test. Details are in the Endpoints & Tunnels docs.

Live-tail incoming deliveries

Once requests are flowing, tail them as they land. The Traffic Inspector shows inbound requests in real time, with searchable payloads, from both the CLI and the dashboard:

# Live-tail deliveries and search payloads
ngris inspect --search "payment_intent" --follow

# Only show deliveries your handler rejected
ngris inspect --status 4xx,5xx

That second command is the one you'll reach for most: it surfaces exactly the deliveries your handler returned an error on, so you can see the payload that broke it. More in the Traffic Inspector docs.

Replay a failed delivery

You don't have to ask the provider to re-fire an event — you replay the captured one. Re-send it to your local handler after a fix, verbatim or with edits to the method, headers, or body:

# Replay a captured delivery verbatim to your local handler
ngris replay --id <req_id>

# Override a header before replaying
ngris replay --id <req_id> --set-header "X-Debug: 1"

Or open the delivery in the local inspector dashboard and hit Replay or Edit & Replay. Replay goes to your tunnel's local backend and doesn't follow redirects, so you re-test a fix against exactly the payload that broke it. See the Replay docs.

Verify signatures at the edge

Most providers sign their webhooks so you can confirm a request really came from them. Instead of writing that check into every handler, enforce it at the edge with a Verify Webhook traffic-policy rule, configured per endpoint:

• secret — the HMAC shared secret from the provider.
• signature_header — the header carrying the signature (defaults to X-Hub-Signature-256, GitHub's convention).
• algorithm — sha256 or sha1.
• signature_prefix — a prefix to strip before comparing, e.g. sha256=.

Requests with a bad or missing signature are rejected before they ever reach your local handler, so you debug only the deliveries that are genuinely from the provider. Full field reference is in the Traffic Policy Rules docs.