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
To install the Stripe CLI with homebrew, run:
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:
- First add the endpoint to your account in the Dashboard’s Webhooks settings section.
- After adding the endpoint, click on its name in the list to access its details.
- On the endpoint details page, click Send test webhook.
- 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.