Stripe Billing Verification

Task

Default to Stripe CLI forwarding for local work. Use ngrok only when the user specifically needs Stripe to deliver to a public HTTPS endpoint.

Quick Reference

export STRIPE_WEBHOOK_SECRET="$(stripe listen --print-secret | tr -d '\r\n')"
LISTENER_LOG=/tmp/stripe-billing-verification/stripe-listen.log
mkdir -p "$(dirname "$LISTENER_LOG")"
stripe listen --forward-to http://localhost:8700/webhooks/stripe \
  2>&1 | tee "$LISTENER_LOG"
stripe trigger payment_intent.succeeded
stripe trigger customer.subscription.created

curl -i http://localhost:8700/webhooks/stripe \
  -X POST \
  -H 'content-type: application/json' \
  -d '{}'

stripe test_helpers test_clocks create --frozen-time <unix-ts>
stripe test_helpers test_clocks advance <clock-id> --frozen-time <unix-ts>

Workflow

1. Ensure local riptide-api is running on http://localhost:8700
2. Capture the CLI forwarding secret with stripe listen --print-secret
3. Export that value as STRIPE_WEBHOOK_SECRET
4. Start a separate stripe listen --forward-to http://localhost:8700/webhooks/stripe process and tee its output to a file so the initial readiness output is preserved even though the process stays attached by design
5. Trigger smoke-test events with stripe trigger ...
6. For lifecycle validation, create a fresh Test Clock, attach a fresh customer, advance the clock, and wait for readiness before asserting results

Secret Rules

• STRIPE_WEBHOOK_SECRET must match the delivery path in use
• Stripe CLI forwarding uses a transient CLI session secret
• Dashboard or Workbench endpoints use that endpoint's signing secret
• these secrets are not interchangeable
• if a signature check fails, first verify that the configured secret matches the traffic source

stripe listen --print-secret is the preferred non-interactive way to capture the local forwarding secret because it prints only the secret and exits. It does not keep the listener running.