Test a webhook endpoint

There are several ways to test your webhook endpoint:

• Create test activity on your account
• Manually send test events from the Dashboard
• Use the Stripe CLI

The first two options both require registering your endpoint with your account, which you will need to do before going live anyway, so the additional effort is low. However, you may experience firewall or tunneling issues when testing these ways, particularly when developing on localhost.

The Stripe CLI is the easiest and fastest method for testing your webhook endpoint. With the Stripe CLI you can begin listening for–and even triggering–events without any additional configuration. This helps you easily test a webhook integration without needing to deploy your application or figure out how to open up your local environment to the public internet in order for Stripe to communicate to it.

Step 1: Install the Stripe CLI

brew install stripe/stripe-cli/stripe

Step 2: Link your Stripe account

After installing the Stripe CLI, pair it with your Stripe account by running stripe login in the terminal. You’ll be prompted to log in to the Stripe Dashboard to grant the Stripe CLI access to your account.

stripe login
Your pairing code is: humour-nifty-finer-magic
Press Enter to open up the browser (^C to quit)

Pairing generates a pair of secret API keys–one test mode, one live mode–that are valid for 90 days.

Step 3: Forward events to your server

After linking your Stripe account, you can use the Stripe CLI to listen for events via stripe listen. But to test your endpoint, you’ll want to forward received events to your server. Do so by adding the --forward-to flag when invoking stripe listen:

stripe listen --forward-to localhost:5000/hooks
Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)

Make sure to replace localhost:5000/hooks with the address and path of your webhook endpoint!

Step 4: Trigger an event

The Stripe CLI has a trigger command that can create certain event types for you. In a new terminal, create a payment_intent.created event:

stripe trigger payment_intent.created

The terminal where you ran the stripe listen command should show the event as well as the response from your server:

stripe listen --forward-to localhost:5000/hooks
Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
YYYY-MM-DD HH:MM:SS  -->  payment_intent.created [{{WEBHOOK_EVENT_ID}}]
YYYY-MM-DD HH:MM:SS  <--  [200] POST http://localhost:5000/hooks [{{WEBHOOK_EVENT_ID}}]

Testing from the Dashboard

To test your webhook endpoint using the Stripe Dashboard:

1. First add the endpoint to your account in the Dashboard’s Webhooks settings section.
2. After adding the endpoint, click on its name in the list to access its details.
3. On the endpoint details page, click Send test webhook.
4. In the modal that appears, select the event type and then click Send test webhook.

The resulting notification and your endpoint’s response are viewable by clicking on the event in the logs below. Do note that these are fake events with fake IDs (e.g., evt_1234). They cannot be fetched through the API and do not contain real, actionable data.

Next steps