Test Stripe webhooks locally
You need a registered account and an API key. Both are free during the beta.
Get a tunnel URLStripe 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
- Signature errors. Almost always a parsed body (re-serialized JSON never matches the signature) or the signing secret from a different endpoint. Each endpoint, and the Stripe CLI, has its own secret. The tunnel passes the body through unchanged.
- The warning page. Browsers opening a tunnel see a one-time notice, but webhook deliveries don't ask for HTML, so Stripe goes straight to your server.
- Slow handlers. Return a 2xx quickly and do slow work afterwards. The tunnel waits up to 100 seconds for your server to start responding, then returns
504. - The URL changes. A tunnel keeps its URL across network reconnects. During the beta a tunnel lasts up to 8 hours; when it expires the client opens a new one with a new URL, and Ctrl-C deletes the tunnel. Either way, update the endpoint in Stripe. Reserved names that stay the same are planned for paid plans after the beta.
- Host-based routing. The client sends
Host: localhost:4242to your server by default and puts the public hostname inX-Forwarded-Host. Use--host-header preserveif your app needs the public host.
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.
More: share a dev server, the tunnel basics and limits, or the tunnel docs.
Get a tunnel URL