# Stripe Billing Verification

Run Stripe webhook smoke tests and billing lifecycle simulations for stripe

- Repository: https://github.com/humanlayer/humanlayer (12740 stars)
- Category: Testing
- License: Apache-2.0
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add humanlayer/humanlayer --skill stripe-billing-verification -g -a claude-code -y`
Codex: `npx skills add humanlayer/humanlayer --skill stripe-billing-verification -g -a codex -y`
Cursor: `npx skills add humanlayer/humanlayer --skill stripe-billing-verification -g -a cursor -y`
Gemini CLI: `npx skills add humanlayer/humanlayer --skill stripe-billing-verification -g -a gemini-cli -y`

## Description

Run Stripe webhook smoke tests and billing lifecycle simulations for stripe

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

## 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

```bash
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
```

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

```bash
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.

The rest: https://github.com/humanlayer/humanlayer/blob/HEAD/.claude/skills/stripe-billing-verification/SKILL.md