Listen to webhook events
Listen for events
After logging in with your Stripe account, you can begin listening for events:
stripe listen
Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
Events are created only when specific actions occur, so you might not see any events until you make an API call or trigger an event directly.
Trigger an event
The Stripe CLI allows you to easily fake event occurrences to test your application. 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:
stripe listen Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit) YYYY-MM-DD HH:MM:SS --> payment_intent.created [{{WEBHOOK_EVENT_ID}}]
Forward events to your server
When developing an application, you’ll likely want to forward received events to your server. Do so using 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)
With forwarding established, events that occur continue to show in the terminal, but you’ll also see 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.succeeded [{{WEBHOOK_EVENT_ID}}] YYYY-MM-DD HH:MM:SS <-- [200] POST http://localhost:5000/hooks [{{WEBHOOK_EVENT_ID}}]
Responses from your server aren’t returned to Stripe and won’t show up in the Dashboard.
Supported events
You can interact with the events triggered through the CLI. These events can also trigger other webhook events (e.g., a payment_intent.succeeded
event also triggers a payment_intent.created
event).
To see a list of supported events, visit the Stripe CLI wiki. If you’d like to see support for an event that isn’t listed above, let us know.
Advanced use cases
The following advanced use cases may not be applicable to your integration with Stripe.
Filter events
The listen
command lets you filter events coming in to your CLI with the --events
flag. This is useful if you only care about or want to test specific events. The flag accepts a comma-separated list of events:
stripe listen --events payment_intent.created,payment_intent.succeeded \ --forward-to localhost:5000/webhook
Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
Use jq
to parse events
The Stripe CLI has the option to print events that come in as JSON instead of the default output. Provide the listen
command with the --print-json
flag to print the JSON to standard output:
stripe listen --print-json
Using the --print-json
flag is useful if you want to work with a tool like jq to filter or manipulate the input. For example, you can display the type of all events Stripe sends to you:
stripe listen --print-json | jq .type
Load your saved endpoints
If you’ve already set up webhook endpoints in the Dashboard, the Stripe CLI has a flag to load and configure those endpoints for you as local forwarding. The flag is --load-from-webhooks-api
and must be used in conjunction with the --forward-to
flag:
stripe listen --load-from-webhooks-api --forward-to localhost:5000
The flag works by loading the endpoints defined in the Dashboard through the Webhooks API. It parses the path and event mapping for each defined endpoint, then appends that path to the --forward-to
path provided while maintaining the event list for each endpoint.
For example, let’s say you defined two endpoints in the Dashboard:
- https://example.com/webhook/charges consumes
charge.created
andcharge.failed
events - https://example.com/webhook/payment-intents consumes
payment_intent.created
events
When you invoke the Stripe CLI with --forward-to localhost:5000
, the Stripe CLI inbounds events to two locations:
- http://localhost:5000/webhook/charges with
charge.created
andcharge.failed
- http://localhost:5000/webhook/payment-intents with
payment_intent.created
Local HTTPS
If you’re developing in a local environment that has self-signed HTTPS certificates, you can disable certificate verification with --skip-verify
.
Stripe Connect
Connect applications involve two Stripe accounts: a platform and a connected account. In some cases, Connect-related events might be sent to a different endpoint than the one standard account events go to. The Stripe CLI supports splitting these events using the --forward-connect-to
flag, which operates similarly to the --forward-to
flag.
Test the latest API version
If you’re on an older version of the Stripe API, you can still test how webhook events behave on the most current API version without upgrading your application. To test webhook events on the latest API version, run the listen
command with the --latest
flag. Using this flag does not actually upgrade your account’s API version and you can run the command safely.
stripe listen --forward-to localhost:5000/hooks --latest
Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)