Connect Stripe to CipherRun.

Create the Stripe Dashboard endpoint

Before you begin, make sure you have workspace-admin access to CipherRun, access to the matching Stripe account, and the deployed CipherRun origin. Create the endpoint in the same Stripe mode as the Checkout flow you are testing: use Test mode for test prices and events, or Live mode for production billing.

In Stripe Dashboard, open Developers → Webhooks, choose Add endpoint, and enter the deployed endpoint below. Subscribe it to checkout.session.completed; that is the event handled by CipherRun's internal checkout provisioning flow.

Save the endpoint, then open its details page. You will copy its signing secret in the next step. If you are only forwarding events to a local process, use the local URL shown in Step 3 instead of saving a production endpoint.

Configure the endpoint signing secret

On the endpoint details page, choose Reveal secret and copy the whsec_... value into the deployed app's STRIPE_WEBHOOK_SECRET environment variable. Redeploy or restart CipherRun after saving the variable so the process loads the new secret.

The endpoint expects Stripe's Stripe-Signature header and the raw JSON request body. When the secret is configured, missing or invalid signatures return 401. In production, an absent secret returns 503 instead of accepting an unsigned request. Keep the secret private and use the secret from the same Stripe mode as the endpoint.

Test delivery with the Stripe CLI

Install the Stripe CLI, authenticate it, and start a listener that forwards Stripe's signed events to your local app. The listener prints a signing secret; use that value as your local STRIPE_WEBHOOK_SECRET, then restart the local server.

For a deployed test endpoint, point the listener at https://<deployed-cipherrun-host>/api/internal/billing/stripe-webhook when appropriate, or send a Dashboard test event to the saved endpoint. A successful delivery shows a 2xx response in the CLI and Stripe event log, and the app log should show the received event.

The generic CLI fixture verifies delivery and signature handling, but it may not provision a tier. Provisioning requires a Checkout Session with a recognized Team or Business price, or matching tier metadata. After a real checkout event, confirm the result in /app/billing.

Know which webhook owns what

The internal endpoint is for checkout.session.completed provisioning only. If you are troubleshooting subscription renewals, plan changes, or cancellations, customer.subscription.updated and customer.subscription.deleted belong to the existing POST /api/stripe/webhook flow, not this internal checkout endpoint.

If delivery fails, first confirm the Stripe mode, endpoint URL, raw-body handling, and matching STRIPE_WEBHOOK_SECRET. Then check the Stripe event delivery log and the CipherRun app log for the response status and event ID.