Guides

Test Stripe webhooks locally

You need a registered account and an API key. Both are free during the beta.

Get a tunnel URL

Stripe delivers webhooks to a public https URL, and your handler is running on localhost. A tunnel closes that gap: Stripe posts to a URL on revshell.org, and the request arrives at your local server with its headers and body intact. These steps use Stripe test mode and a Node.js handler on port 4242, but any language and port work.

1. Run your handler

Signature checks need the raw request body, so don't let a JSON body parser run on the webhook route first. With Express and the official stripe package:

const express = require("express");
const stripe = require("stripe")(process.env.STRIPE_SECRET_KEY);
const app = express();

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = stripe.webhooks.constructEvent(
      req.body,                          // raw Buffer, not parsed JSON
      req.headers["stripe-signature"],
      process.env.STRIPE_WEBHOOK_SECRET, // whsec_... from step 3
    );
  } catch (err) {
    return res.status(400).send(`Bad signature: ${err.message}`);
  }
  console.log("got", event.type);
  res.sendStatus(200);
});

app.listen(4242);

2. Open a tunnel to port 4242

Create an API key on your account page, then run this in a second terminal. It fetches a small native client for your OS, so there is nothing else to install:

(curl -fsSL https://revsheller.com/tn.sh || wget -qO- https://revsheller.com/tn.sh) | RSH_API_KEY=rsh_YOUR_KEY sh -s -- http 4242

On Windows PowerShell:

$env:RSH_API_KEY="rsh_YOUR_KEY"; & ([scriptblock]::Create((irm https://revsheller.com/tn.ps1))) http 4242

The client prints your public URL, for example https://tn-k3v9q2m7xa.revshell.org. Leave it running.

3. Add the endpoint in Stripe

In the Stripe Dashboard, switch to test mode and add a webhook endpoint (under Developers, Webhooks). Use your tunnel URL plus the route, for example https://tn-k3v9q2m7xa.revshell.org/webhook, and pick the events you handle. Stripe then shows the endpoint's signing secret, which starts with whsec_. Put it in STRIPE_WEBHOOK_SECRET and restart the handler.

4. Send an event

Send a test event from the endpoint's page in the Dashboard, or create real test-mode activity, for example with the Stripe CLI's stripe trigger payment_intent.succeeded. The tunnel client logs one line per request, and your handler prints the event type. If something fails, the endpoint's delivery log in Stripe shows the status code your server returned.

Things that trip people up

When the Stripe CLI is enough

If you only need Stripe events on your own machine, stripe listen --forward-to localhost:4242/webhook works without any public URL. A tunnel is the better fit when you want to test a real endpoint configured in the Dashboard, receive webhooks from other providers in the same session, or let a teammate hit your local server.

GitHub webhooks work the same way

In your repository's settings, add a webhook with the tunnel URL plus your route as the payload URL, content type application/json, and a secret. GitHub signs each delivery in X-Hub-Signature-256: an HMAC-SHA256 of the raw body with that secret. Verify it against the raw bytes, exactly as with Stripe. The webhook's Recent Deliveries tab lets you redeliver a payload while you fix your handler.

Clean up

Press Ctrl-C in the tunnel terminal to delete the tunnel, and remove or disable the test endpoint in Stripe so it doesn't keep failing deliveries to a URL that no longer exists.

FAQ

Will Stripe hit the browser warning page?
No. Only browsers loading a page see it.

Why does signature verification fail?
Usually a parsed body or the wrong signing secret. Verify the raw bytes with the secret of this endpoint.

Does the URL stay the same?
While the tunnel is open, yes, for up to 8 hours during the beta.

Should I use the Stripe CLI instead?
For Stripe alone on your own machine, it is simpler. Use a tunnel for real endpoints, other providers, or sharing.