Listen to webhooks events
The Stripe CLI allows you to listen, trigger, and forward webhooks events from the terminal.
Step 1: 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.
Step 2: 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.succeeded [{{WEBHOOK_EVENT_ID}}]
Step 3: 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}}]
Supported events
Events triggered through the CLI are real objects in the Stripe API that you can interact with. 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 follow sections are more advanced use cases that 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.createdandcharge.failedevents - https://example.com/webhook/payment-intents consumes
payment_intent.createdevents
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.createdandcharge.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.
Work with 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.
Testing 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)