Test Stripe webhooks locally

To test the Stripe webhooks on your local machine follow these steps:

Step 1: Setup

First, install the Stripe CLI by downloading and running the executable file. This is a command line tool that allows you to send webhooks to your local server.

Once you installed the CLI, you need to log in to your Stripe account. Run the following command to log into Stripe:

stripe login

Step 2: Forward events to the local webhook endpoint

You can forward events to your local server using the Stripe CLI command:

stripe listen --forward-to localhost:3000/api/webhooks # <-- your local webhook endpoint

When you run this command you'll see a webhook secret in the console output:

> Ready! You are using Stripe API Version [2020-08-27]. Your webhook signing secret is whsec_... (^C to quit)

Add this whsec_... secret key to your .env.local file as STRIPE_WEBHOOK_SECRET.


Step 3: Start your local development server

Next, start your local server by running the following command in the root directory of your project:

npm run dev

By default, this project will start at http://localhost:3000 (and Stripe events will be forwarded to http://localhost:3000/api/webhooks).

Step 4: Send a test webhook event

You can now send a test webhook event to your local server in 1 of 2 ways:

Option 1 - Using the Stripe CLI

Now that your server is running, you can trigger a test webhook event using the Stripe CLI. Run the following command to trigger a payment_intent.succeeded event:

stripe trigger payment_intent.succeeded

This will send a webhook event to your local server. You can confirm that the webhook was received by checking your local server logs. The following logs should be visible in the console:

Stripe webhook event logs

Option 2 - Creating a new test subscription on your local machine

You can also create a new test subscription on your local machine by following the normal checkout flow in the boilerplate (http://localhost:3000/pricing) and using the Stripe test credit card details to complete the payment. This will trigger all the webhook events related to signup and it will be forwarded to your local server.

To change how webhook events are processed and saved in this boilerplate, modify the pages/api/webhooks.ts file.

Last updated:

Want to know how to easily build your SaaS?

Sign up for the Ship SaaS newsletter to get notifiedabout the latest updates and blog posts

We care about the protection of your data. Read our Privacy Policy and Terms & Conditions.