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
brew install stripe/stripe-cli/stripe

sudo apt-key adv --keyserver hkp://pool.sks-keyservers.net:80 --recv-keys 379CE192D401AB61
sudo apt-key adv --keyserver hkp://pool.sks-keyservers.net:80 --recv-keys 379CE192D401AB61

echo "deb https://dl.bintray.com/stripe/stripe-cli-deb stable main" | sudo tee -a /etc/apt/sources.list
echo "deb https://dl.bintray.com/stripe/stripe-cli-deb stable main" | sudo tee -a /etc/apt/sources.list

sudo apt-get update
sudo apt-get update

sudo apt-get install stripe
sudo apt-get install stripe

wget https://bintray.com/stripe/stripe-cli-rpm/rpm -O bintray-stripe-stripe-cli-rpm.repo && sudo mv bintray-stripe-stripe-cli-rpm.repo /etc/yum.repos.d/
wget https://bintray.com/stripe/stripe-cli-rpm/rpm -O bintray-stripe-stripe-cli-rpm.repo && sudo mv bintray-stripe-stripe-cli-rpm.repo /etc/yum.repos.d/

sudo yum install stripe
sudo yum install stripe

scoop bucket add stripe https://github.com/stripe/scoop-stripe-cli.git
scoop bucket add stripe https://github.com/stripe/scoop-stripe-cli.git

scoop install stripe
scoop install stripe

docker run --rm -it stripe/stripe-cli latest
docker run --rm -it stripe/stripe-cli latest

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)
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)
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
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)
INFO Received event: '{{WEBHOOK_EVENT_ID}}' [type: payment_intent.created]
INFO Got response from local endpoint, status=200
stripe listen --forward-to localhost:5000/hooks
Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
INFO Received event: '{{WEBHOOK_EVENT_ID}}' [type: payment_intent.created]
INFO Got response from local endpoint, status=200

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

• Check the webhook signatures
• Best practices for using webhooks
• Take webhooks live
• Using the Stripe CLI