MercurALPHA
Sign inCreate a free account

Test webhooks locally

Webhooks need a publicly reachable URL. Localhost alone cannot receive callbacks from Stripe, GitHub, or Twilio. Mercur gives you a public HTTPS endpoint so you can test webhooks locally — inspect first in the browser, then forward to a process on your machine when you are ready.

How it works

  1. Open the online webhook tester — no account, no install
  2. Copy the temporary public HTTPS URL
  3. Register that URL with your webhook provider (or send a test with curl)
  4. Inspect method, headers, and body in request history
  5. When you need localhost: create a free account, start an Endpoint, install the macOS agent, and forward deliveries to your local port

Quick example

Open the webhook tester

Copy the HTTPS URL from the page, then send a sample delivery:

Run
curl -X POST "$MERCUR_URL" \
-H "Content-Type: application/json" \
-d '{"hello":"webhook"}'

Paste the same URL into a provider dashboard (Stripe, GitHub, Shopify, Twilio, and others). Guest mode records the request and responds 204 No Content.

Inspect webhook payloads

Open request history on the tester (or in the console for an Endpoint). Each entry shows headers and body as the provider sent them — including signature headers such as Stripe-Signature or X-Hub-Signature-256.

That is enough to debug most integrations without adding logging to your app yet.

Replay failed webhooks

After you fix a handler, you often want the same payload again without waiting on the provider. In the console, open request history for the Endpoint and choose Retry. Mercur re-sends the stored method, path, headers, and body through the public URL.

Requirements:

  • Endpoint in proxy mode (not logging-only)
  • Agent connected
  • Payload still stored (within plan retention and size limits)

Oversized bodies that were omitted from the log cannot be replayed.

Verify webhook signatures

Providers sign each request with a secret so your app can confirm authenticity. Keep that secret in your local environment — not in Mercur.

Use Mercur’s request history to compare the raw body and signature header with what your verifier expects. Encoding and whitespace matter; mismatches usually show up as a failed check in your handler while the delivery itself looks fine in the log.

Forward to localhost

When inspection is not enough and your local server must respond:

  1. Create a free Mercur account
  2. Start an Endpoint aimed at your local port
  3. Install the macOS agent and sign in
  4. Point the provider at the Endpoint URL (or keep the guest URL for inspect-only work)

Install the macOS agent

Guest mode does not forward traffic. Forwarding and Retry need an account, a proxy Endpoint, and a connected agent.

Next steps

Test a webhook here