ericrisco/rsc-harness / skills/stripe
stripe
VerifiedUse when wiring an app to Stripe for payments, subscriptions, Checkout, webhooks or the billing portal — adding a paywall or paid plan, charging recurring fees, and debugging why a completion event never fires, why signature verification fails, or why a webhook fires twice and duplicates the order. NOT a generic non-Stripe inbound event receiver (that is `webhooks`), NOT the invoice document's legal form (that is `invoicing`), NOT deciding what to charge (that is `pricing`).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.6 KB |
| evals/README.md | markdown | 707 B |
| evals/cases.yaml | config | 2.8 KB |
| references/going-live.md | markdown | 2.7 KB |
| references/webhook-events.md | markdown | 3.3 KB |
| scripts/verify.shexecutable | script | 4.7 KB |
references/webhook-events.md
View on GitHub# Stripe webhook events — catalog per flow
What to listen for and what each event should do to your DB. Subscribe to only
the events a flow needs; "send all events" is discouraged.
## Subscription paywall
| Event | What it means | DB action |
|---|---|---|
| `checkout.session.completed` | Customer finished Checkout (paid or trial started) | Link `client_reference_id` (your user) to `session.customer`; mark provisional access. |
| `customer.subscription.created` | Subscription now exists | Store `subscription.id`, `status`, `current_period_end`, price ID. |
| `customer.subscription.updated` | Plan changed, renewed, trial→active, past_due, canceled-at-period-end | Re-sync `status` and `current_period_end`. This is the workhorse; gate access on `status`. |
| `customer.subscription.deleted` | Subscription ended | Revoke access. |
| `invoice.paid` | A billing cycle was paid | Confirm/extend access; optionally store the invoice ref. |
| `invoice.payment_failed` | A charge failed | Enter dunning (below); do not revoke immediately. |
Gate access on `subscription.status` (`active` or `trialing` = entitled;
`past_due`/`unpaid`/`canceled` = not), not on a single "is_pro" boolean you
set once at checkout.
## One-time payment
| Event | DB action |
|---|---|
| `checkout.session.completed` (mode `payment`) | Fulfill the order / unlock the download. The primary signal. |
| `payment_intent.succeeded` | Optional confirmation if you also create PaymentIntents directly. |
## Dunning (failed payment)
`invoice.payment_failed` starts Stripe's automatic retry schedule (Smart
Retries / your dunning settings). Do not revoke on the first failure — Stripe
will retry. Mark the account `past_due` and surface a "update your card"
prompt (link to the billing portal). Revoke only when
`customer.subscription.deleted` fires.
## Thin events vs snapshot events
- **Snapshot events** (`event.data.object`) embed a full object snapshot at send
time. Convenient, but the object may already be stale by the time you process
it out of order.
- **Thin events** carry only IDs; you fetch the current object yourself. They
are inherently fresher.
Whichever you receive, for state that matters (subscription status), re-fetch
or trust the latest `customer.subscription.updated` rather than reconstructing
state from an ordered sequence — events are not ordered.
## Raw-body recipes by framework
```ts
// Express — raw on this route only; keep express.json() for other routes.
app.post("/webhook", express.raw({ type: "application/json" }), handler);
```
```ts
// Next.js App Router — route segment runs on Node by default; read raw text.
export async function POST(req: Request) {
const body = await req.text();
const sig = req.headers.get("stripe-signature")!;
const event = stripe.webhooks.constructEvent(body, sig, secret);
// ...
return new Response(null, { status: 200 });
}
```
```ts
// Next.js Pages Router — disable the body parser, read the raw stream.
export const config = { api: { bodyParser: false } };
```
```ts
// Edge / Workers — no Node crypto; use the async API + Web Crypto provider.
const event = await stripe.webhooks.constructEventAsync(
body, sig, secret, undefined, Stripe.createSubtleCryptoProvider(),
);
```
The header name is lowercase `stripe-signature`. Default replay tolerance is
5 minutes; a clock skew larger than that rejects valid events.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |