Sign in
Create account
Sign in
Support
HomeDeveloper toolsStripe CLI

Listen to webhook events

The Stripe CLI allows you to listen, trigger, and forward webhook events from the terminal.

Listen for events

After logging in with your Stripe account, you can begin listening for events:

Terminal
stripe listen
Output
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:

Terminal
stripe trigger payment_intent.created

The terminal where you ran the stripe listen command should show the event:

Output
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:

Terminal
stripe listen --forward-to localhost:5000/hooks
Output
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:

Terminal
stripe listen --forward-to localhost:5000/hooks
Output
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:

Terminal
stripe listen --events payment_intent.created,payment_intent.succeeded \
  --forward-to localhost:5000/webhook
Output
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:

Terminal
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:

Terminal
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:

Terminal
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 and charge.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 and charge.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.

Terminal
stripe listen --forward-to localhost:5000/hooks --latest
Output
Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
Was this page helpful?
Questions? Contact us.
Developer tutorials on YouTube.
On this page
Listen for events
Trigger an event
Forward events to your server
Supported events
Advanced use cases