Stripe guide

How to test Stripe webhooks locally

Get Stripe test events to your local server, verify them with your real signing secret, and replay them while you fix your handler.

Updated 9 November 2026 · 8 minute read

Stripe can only send webhooks to a public HTTPS URL, and your handler runs on localhost. This guide covers the three ways to close that gap, then walks through the one that keeps a history of every event so you can replay it after you change your code.

Three ways to get Stripe events to localhost

ApproachGood atWatch out for
Stripe CLI (stripe listen)Free, official, quick to start, stripe trigger creates test eventsOnly Stripe, and only while the terminal is open. It prints its own signing secret, which differs from your dashboard endpoint's. Resending a past event (stripe events resend) goes to every endpoint again.
A tunnel (ngrok, Cloudflare Tunnel)Works for any provider and any HTTP trafficYou need a fixed hostname (ngrok's free static domain or a named Cloudflare Tunnel) to avoid updating Stripe. Requests that arrive while your laptop is asleep are lost.
A webhook relay (SlingHook)A fixed URL that records every request, forwards it to localhost, and replays it on demandOne more account. The free plan keeps 24 hours of history.

If you only need to see one event once, the Stripe CLI is fine. If you are building a handler over several days, a fixed URL with history saves you from creating a new test payment every time you change a line.

1. Get a fixed webhook URL

Sign up (or try it without an account) and SlingHook creates an endpoint for you. Its URL looks like this:

https://slinghook.co.za/c/9f2c41d0-7a3e-4b8e-a1f5-2d6c8e0b3a17

The URL doesn't change, so you add it to Stripe once.

2. Add the URL in Stripe (test mode)

  1. In the Stripe Dashboard, switch to Test mode.
  2. Go to Developers → Webhooks (Workbench in newer dashboards). Add an endpoint, then paste your SlingHook URL.
  3. Pick the events your code handles, for example checkout.session.completed, invoice.paid and customer.subscription.updated.
  4. Open the new endpoint and copy its Signing secret. It starts with whsec_.

Paste the same whsec_ secret into your endpoint's settings in SlingHook too. SlingHook then checks every request it catches and tells you when a signature would fail.

3. Forward events to your machine

Install nothing globally; npx runs the CLI. Sign in once, then listen:

npx slinghook login
npx slinghook listen 9f2c41d0-7a3e-4b8e-a1f5-2d6c8e0b3a17 --forward http://localhost:3000/webhooks/stripe

The CLI makes an outbound connection, so there are no open ports or firewall rules. Each event arrives at your local server with Stripe's original headers and body, including Stripe-Signature, so your normal verification code works unchanged.

4. Verify the signature in your handler

Stripe signs the exact bytes it sends. Verify against the raw body, before any JSON parser touches it. In Express:

import express from 'express';
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const app = express();

// Raw body for this route only. Register it before app.use(express.json()).
app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), (req, res) => {
    let event;
    try {
        event = stripe.webhooks.constructEvent(
            req.body,                              // a Buffer, not a parsed object
            req.headers['stripe-signature'],
            process.env.STRIPE_WEBHOOK_SECRET      // the whsec_ from step 2
        );
    } catch (err) {
        return res.status(400).send(`Webhook error: ${err.message}`);
    }

    if (event.type === 'checkout.session.completed') {
        // fulfil the order
    }
    res.json({ received: true });
});

app.listen(3000);

The same idea in PHP, with stripe/stripe-php:

$payload = file_get_contents('php://input');
$header  = $_SERVER['HTTP_STRIPE_SIGNATURE'] ?? '';

try {
    $event = \Stripe\Webhook::constructEvent($payload, $header, getenv('STRIPE_WEBHOOK_SECRET'));
} catch (\UnexpectedValueException | \Stripe\Exception\SignatureVerificationException $e) {
    http_response_code(400);
    exit;
}

If verification fails, read Stripe webhook signature verification failed: every cause and fix.

5. Send yourself a test event

Any of these work:

  • Do the real thing in test mode. Run a Checkout session and pay with the test card 4242 4242 4242 4242. You get the same sequence of events a real customer would cause.
  • Use the Stripe CLI's trigger. stripe trigger checkout.session.completed creates the objects and fires the event at every endpoint in your test account, including your SlingHook URL.
  • Use SlingHook's simulator. Press Simulate above the feed and pick a Stripe event. With your whsec_ saved on the endpoint, the event is signed the way Stripe would sign it.

6. Change your code and replay

This is where a recorded URL pays off. When your handler throws, fix it and press Replay on the event in SlingHook. The same request goes to localhost again, so you don't create another payment to test one line. Each replay shows whether your handler now succeeds, and on Pro, fix verification puts the new response next to the old one.

One catch: Stripe's libraries reject a signature older than 5 minutes (the tolerance). A replay sends the original Stripe-Signature, so replaying an older event fails that check. In development only, pass a larger tolerance, for example constructEvent(body, header, secret, 86400) in Node or Webhook::constructEvent($payload, $header, $secret, 86400) in PHP. Keep the default in production.

Checklist

  • Test mode endpoint pointing at your fixed URL
  • The endpoint's own whsec_ secret in your .env, not the one stripe listen printed
  • Raw body on the webhook route
  • Return a 2xx quickly and do slow work in a queue; Stripe retries anything else
  • Handle the same event twice safely: store event.id and skip ones you've already processed

Catch your Stripe webhooks in one place.

Free plan, no card needed. Your URL is ready as soon as you sign up.

Get a free endpoint