stripe_listen

stripe_listen starts the selected managed Stripe CLI, obtains its webhook signing secret, and forwards snapshot webhook events to a local HTTP or HTTPS URL. It returns a dependency that resolves after Stripe reports that the listener is ready. The dependency sets STRIPE_WEBHOOK_SECRET for dependent tasks.

load("@os@1", "env_set", "os_run")
load("@[email protected]", "stripe_listen")

listener = stripe_listen(
    forward_to="http://localhost:4321/api/stripe/connect_webhook",
    deps=[env_set("STRIPE_API_KEY", "sk_test_...")],
)

os_run(("pnpm", "dev"), deps=[listener])

stripe_listen first runs stripe listen --print-secret, then starts stripe listen --forward-to. The secret is kept in memory, suppressed from Stripe output, and checked against the running listener before the dependency resolves. Stripe documents that this secret remains stable between listener restarts.

Authentication

Authentication is selected in this order:

1. Non-empty STRIPE_API_KEY from the virtual environment after activating deps.
2. Non-empty host XX_STRIPE_API_KEY.
3. Project-scoped XX_STRIPE_API_KEY from the builtin xx secret manager.
4. Existing Stripe CLI credentials from the host profile and operating-system keyring.

Store the fallback key without putting it in shell history:

printf %s 'sk_test_...' | xx secrets set XX_STRIPE_API_KEY

xx never runs stripe login. Before using host credentials, it runs stripe whoami with the managed CLI. All authentication and listener commands receive non-terminal standard input, which disables Stripe CLI automatic login. Missing or invalid credentials fail without starting an interactive flow.

STRIPE_API_KEY supplied through deps remains part of the dependency environment and therefore reaches downstream tasks. Host or stored XX_STRIPE_API_KEY is translated to STRIPE_API_KEY only in Stripe CLI child processes and is not exposed downstream.

Stripe CLI also requires a device name. stripe_listen respects a non-empty STRIPE_DEVICE_NAME from the selected environment and otherwise uses xx.

Arguments

The listener is a long-running root. xx remains active while it is running. Canceling xx terminates the Stripe process tree automatically. An unexpected exit, readiness timeout, changed signing secret, or output failure fails the run and cancels sibling tasks.