stripe-listen

Forward Stripe webhook events to a local server

TLDR

Listen for all snapshot events in the terminal

$ stripe listen

Forward events to a local webhook endpoint

$ stripe listen --forward-to [localhost:3000/webhook]

Forward selected event types

$ stripe listen --events [payment_intent.succeeded,payment_intent.payment_failed] --forward-to [localhost:3000/webhook]

Print events as JSON

$ stripe listen --format [JSON]

Print only the webhook signing secret and exit

$ stripe listen --print-secret

Forward Connect events to a second URL

$ stripe listen --forward-to [localhost:3000/webhook] --forward-connect-to [localhost:3000/connect-webhook]

Skip TLS verification when forwarding to HTTPS

$ stripe listen --forward-to [https://localhost:3000/webhook] --skip-verify

stripe listen is a subcommand of the Stripe CLI. It opens a direct connection to Stripe and streams webhook events to the terminal. With --forward-to, each event is also POSTed to a local HTTP endpoint so webhook handlers can be tested without a public URL or a tunnel.On start the command prints a webhook signing secret. Use that value with Stripe's signature verification libraries. The secret is session-specific and changes each time listen is run.--events accepts both snapshot types (`paymentintent.succeeded`) and thin types namespaced by API version (`v1.billing.meter.nometer_found`). --all-thin and --events-from @accounts cover thin events and Connect accounts.

PARAMETERS

-e, --events types

Comma-separated snapshot or thin event types to receive (e.g. `charge.captured`, `v1.billing.meter.nometerfound`). Default is all snapshot events.

--all-snapshot

Subscribe to every snapshot event.

--all-thin

Subscribe to every thin event.

--events-from source

Which accounts to receive events from: `@self` (your account), `@accounts` (connected accounts), or `all` (default).

-f, --forward-to url

URL that received events are POSTed to.

-c, --forward-connect-to url

URL for Connect events. Defaults to --forward-to.

-H, --headers headers

Extra headers to send when forwarding, as `Key:Value` pairs.

--connect-headers headers

Extra headers for Connect forwards, as `Key:Value` pairs.

-l, --latest

Receive events formatted with the latest API version instead of the account default.

--live

Receive live-mode events. Requires a live-mode login; check with stripe whoami.

--format JSON

Print full event payloads as JSON. Prefer this over the deprecated --print-json.

--print-secret

Print the webhook signing secret (`whsec_...`) and exit.

-a, --use-configured-webhooks

Load endpoint configuration from the webhooks API / Dashboard instead of a local URL.

--skip-verify

Skip TLS certificate verification when forwarding to HTTPS endpoints.

INSTALL

brew install stripe

CAVEATS

Requires stripe login (or --api-key). Events are delivered only while the process is running; events that fire while it is stopped are missed.--live is required in live mode and rejected in a sandbox. Organization sandboxes are not supported.The signing secret printed at start is not the same as a Dashboard endpoint secret. Update local verification when you restart listen.--print-json is deprecated; use --format JSON. --thin-events, --forward-thin-to, and --forward-thin-connect-to still work but are deprecated in favor of --events / --all-thin and --forward-to.

HISTORY

The Stripe CLI was released by Stripe in 2019. listen was a primary reason for the CLI: local webhook testing without third-party tunnels.

RESOURCES

Documentation · Homepage · Source code