Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 38 ยท Testing and Fraud

Testing Webhooks Locally

Learn how to receive Stripe webhooks on your own machine with the Stripe CLI, trigger sample events, write automated tests with signed fixtures, and replay events after fixing bugs.

Stripe cannot reach localhost, so how do you develop a webhook handler on your laptop? There are three complementary techniques: forward real test events to your machine, trigger events on demand, and write automated tests that sign their own fixtures. Together they let you build handlers with confidence before any real customer is involved.

The Stripe CLI and the Stripe API cannot run in this sandbox (no network, no installable programs), so the CLI commands are read-only. The automated-testing technique, however, runs right here.

Technique 1: forward events with the Stripe CLI

The CLI opens a connection to Stripe and relays events to a local URL.

Terminal
# Read-only: run these on your own machine
stripe login
stripe listen --forward-to localhost:3000/webhooks/stripe
# prints:  Ready! Your webhook signing secret is whsec_... 

stripe listen prints a signing secret specific to this session. Put it in your local environment variable. It differs from the secret of a production endpoint, which is a common source of "signature mismatch" confusion.

Technique 2: trigger sample events

Terminal
# Read-only
stripe trigger payment_intent.succeeded
stripe trigger invoice.payment_failed
stripe trigger customer.subscription.deleted

The CLI creates the necessary objects in test mode and Stripe sends the resulting events to the listener. Fixture events are generic, so also run a real test checkout to see events with your own metadata.

flowchart LR
  T["stripe trigger"] --> S["Stripe test mode"]
  S --> L["stripe listen"]
  L -->|forward| H["localhost handler"]
  H --> D[("Local database")]

Events travel through Stripe, then the CLI, then your code.

Technique 3: automated tests with signed fixtures

Manual clicking does not protect you from regressions. In your test suite, build an event, sign it with a test secret exactly as Stripe would, send it to your handler and assert the outcome. Nothing leaves your machine.

Node.js A handler plus a signed-fixture test

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The first request must be rejected with 400 and leave the order untouched; the second must succeed. Add a test for each event type you handle, for duplicates (send the same event twice) and for out-of-order delivery.

Node.js A tiny test runner for webhook rules

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Replay and the Dashboard

Fixed a bug in a handler? In the Dashboard open the event and choose to resend it to an endpoint, or use stripe events resend evt_... from the CLI. This is far better than recreating the payment. For production, also keep your own copy of the raw events so you can replay them locally.

When a local handler returns 400 on every event, compare the secret printed by stripe listen with the one in your .env first. Mismatched secrets cause most local verification failures.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why can't Stripe send webhooks directly to localhost?

    Stripe's servers cannot reach a private address, so the CLI relays events instead.
  2. 2. What does stripe trigger do?

    It performs API calls in test mode that generate the events you want to test.
  3. 3. Why sign fixtures in automated tests?

    Signing with a test secret lets the handler's real verification run without Stripe.
  4. 4. Which scenario should always have its own test?

    At-least-once delivery means duplicates are guaranteed to happen, so test for them.

Summary

  • Use stripe listen to forward test events to localhost and stripe trigger to create them.
  • The CLI session secret differs from your production endpoint secret.
  • Automated tests should sign their own fixtures and cover duplicates and bad signatures.
  • Resend events from the Dashboard or CLI after fixing a bug.

Next: Radar and Fraud Prevention