← Back to Guides · Setup Guide
Claude Code Rules for SaaS Billing & Stripe Webhooks: Setup Guide 2026
Short answer: set up Stripe webhooks in Claude Code by installing a SKILL.md at .claude/skills/stripe-billing-webhooks/SKILL.md that forces the agent to read the raw request body before verifying the signature, write every processed event ID to a unique-constrained table before running side effects, and sync subscription state only from Stripe's own customer.subscription.* events — never from the Checkout success redirect. Below is the exact skill file, annotated line by line, the one failure mode that causes most double-charges, and how it compares to doing the same thing with Cursor rules.
If you already have an opinion on rules vs. skills, skip to the skill file. If you're deciding which format to use for Stripe code specifically, see Cursor rules for Stripe & billing codebases first — the short version is that the four bans in that post (signature verification, idempotency, subscription-state source of truth, secret hygiene) belong in an always-on rule, and the full procedure below belongs in a skill the agent loads only when the task is actually Stripe.
Why generic webhook handling misses idempotency and signature verification
Ask Claude Code to "add a Stripe webhook handler" with no skill loaded and you typically get working-looking code that fails in two specific ways once it hits production traffic, not local testing:
- Signature verification against the wrong body.
stripe.webhooks.constructEventneeds the exact raw bytes Stripe sent. If the handler calls a JSON body parser first — which is the default in most framework examples the model has seen — the body gets re-serialized before verification, and the signature check fails on every request, not just malicious ones. The usual "fix" an agent reaches for is disabling verification, which is worse than the bug. - No idempotency. Stripe explicitly recommends designing webhook endpoints to handle duplicate events, because its own delivery model retries on timeout or non-2xx and can send the same event more than once under normal operation. A handler with no dedupe key processes a retried
checkout.session.completedtwice, which shows up as a customer charged twice or upgraded two tiers in one click.
Both failures are invisible in a manual test where you fire one webhook once. They only appear under Stripe's real delivery behavior, which is why they ship so often.
The skill file, annotated line by line
SKILL.md contents
Create .claude/skills/stripe-billing-webhooks/SKILL.md:
---
name: stripe-billing-webhooks
description: Set up or fix Stripe Checkout and webhook handling for a SaaS app — signature verification, idempotent event processing, and subscription state sync. Use when the user asks to add Stripe billing, fix a webhook, or debug a subscription that's out of sync with Stripe.
---
# Stripe Billing Webhooks
## Signature verification
- Read the webhook body with request.text() (or the raw-body equivalent for the framework) before any JSON parsing. A body that has been parsed and re-serialized will not match the signature Stripe sent.
- Pass that raw string, not a parsed object, to stripe.webhooks.constructEvent.
- Keep separate STRIPE_WEBHOOK_SECRET values per environment (test vs. live) and fail at boot if the one for the current environment is missing.
- Return 400 on a bad signature. Do not fall back to trusting the payload.
## Idempotent processing
- Insert the Stripe event id into a unique-constrained processed_events table before running any side effect. If the insert conflicts, the event was already handled; return 200 and stop.
- Never branch handler logic on headers, timestamps, or retry counts. Only the event id decides whether work has already happened.
- Return a 2xx response within a few seconds. Push slow work (receipt emails, exports, analytics) to a queue after the event is recorded, so Stripe's own timeout doesn't trigger a retry on work that already started.
## Subscription state is Stripe's, not the redirect's
- Update plan, status, and current_period_end only from customer.subscription.created/updated/deleted events.
- Never grant access from the Checkout success redirect. A closed tab or dropped connection means the redirect never fires even though payment succeeded — the webhook is the only reliable signal.
- On invoice.payment_failed, move the account to past_due. Don't revoke access until the subscription itself is canceled or past its grace period.
- Pass client_reference_id or metadata with your internal user/org id at Checkout session creation, so later events can be tied back to an account without matching on email.
- On an out-of-order or stale-looking event, re-fetch the object from the Stripe API rather than trusting the event payload as the latest state.
## Before calling it done
Run this checklist and report the result of each line, not just "done":
1. A request with a tampered or missing signature returns 400.
2. Replaying the same event id (same payload, sent twice) produces no second side effect.
3. invoice.payment_failed moves the account to past_due without revoking access immediately.
4. Canceling at period end keeps access until current_period_end, not immediately.
5. The Stripe CLI (stripe trigger <event>, stripe listen --forward-to) can replay each event type locally.
## Output
List the files written, which event types are handled, and the checklist results above with the actual command run for each, not just a claim that it passes.
Why each section is built this way:
- Raw body first is the single highest-frequency Stripe bug in agent-written code, so it's rule 1, not a footnote. It's easy to miss because most framework quick-starts parse the body before anything else by default.
- The unique-constrained table, not an in-memory set, is the dedupe mechanism, because the handler needs to survive process restarts and horizontal scaling. An in-memory "seen event IDs" list resets on every deploy and doesn't work across more than one instance.
- Subscription state sync is scoped to a narrow list of event types. This stops the agent from wiring "give the user access" to the Checkout success page, which is the most common place an agent defaults to because it's the most obvious place in the UI flow — it just isn't a reliable signal.
- The checklist asks for the command run, not a claim. An agent that reports "idempotency: done" after writing the insert-on-conflict line has not actually proven it; asking for the Stripe CLI command and its output forces a real check.
Common failure: retried webhooks causing duplicate charges
This is the failure mode worth debugging in detail, because it's the one that reaches a customer instead of failing a test. Stripe's delivery guarantee is at-least-once, not exactly-once — their webhook docs are explicit that your endpoint can receive the same event more than once and that you're responsible for deduplication. The usual chain of events:
- Your handler does real work (grants access, sends a receipt, or in the worst case creates a second charge via a follow-up API call) and then is slow to respond — a cold start, a slow DB write, a downstream API call inside the request path.
- Stripe doesn't see a 2xx within its timeout window and retries the same event.
- Without a dedupe check, the handler runs the same side effect again.
The fix is exactly the idempotent-processing section above: insert the event id into a table with a unique constraint before running any side effect, and treat a conflicting insert as "already done, return 200." If you're seeing this in production right now, the fastest diagnostic is the Stripe Dashboard's webhook event log — it shows every delivery attempt per event, including retries, so you can confirm whether an event was actually sent twice before assuming the bug is elsewhere.
Porting the same logic from Cursor rules
If your team already uses Cursor on the same repo, you don't need to re-derive this logic twice. Cursor rules for Stripe & billing codebases covers the same four failure modes — signature verification, idempotency, subscription-state source of truth, and secret hygiene — as four short, glob-scoped .mdc rule files instead of one skill. The difference is format and trigger, not content:
| Cursor rule | Claude Code skill | |
|---|---|---|
| Where it lives | .cursor/rules/*.mdc, glob-scoped to app/api/stripe/** etc. | .claude/skills/stripe-billing-webhooks/SKILL.md |
| When it loads | Automatically, on every matching file | When the agent's task description matches the skill's description field |
| Best for | Short, checkable bans ("never trust the redirect for access") | The fuller procedure, including the pre-launch checklist and CLI commands to run |
In practice the four rules and this skill's first three sections say the same thing, because the underlying Stripe behavior doesn't change by editor. If you're already running the Cursor rules on part of the codebase, copy the four bullet points verbatim into the skill's equivalent sections rather than rewriting them — they were written against the same webhook delivery model.
FAQ
Where does a Claude Code Stripe skill file go? .claude/skills/stripe-billing-webhooks/SKILL.md — a folder per skill, with a SKILL.md containing YAML frontmatter (name, description) and a markdown body. Claude Code matches your request against the description field to decide when to load it.
Why does webhook signature verification fail even though the secret is correct? Almost always because the request body was parsed into JSON and re-serialized before being passed to stripe.webhooks.constructEvent. Pass the original raw string from request.text() (or your framework's raw-body equivalent), not a parsed-then-stringified object.
Can a Stripe webhook really be delivered twice without anything being wrong? Yes — Stripe's own documentation states its delivery model is at-least-once and that your endpoint should expect and handle duplicate events, not treat a repeat as a bug on Stripe's side.
Running Cursor instead, or alongside Claude Code? Best Cursor Skills for Stripe Billing and Subscription SaaS covers the equivalent skill/rule setup for dunning, billing portal UI, and refunds/proration on top of the three sections above.
Should subscription access ever be granted from the Checkout success page? No. The redirect is a UX nicety, not a reliable event — a closed tab or dropped connection means it never fires even though the payment succeeded. Grant and revoke access only from the customer.subscription.* webhook events.
Do I need this skill if I already use the Cursor rules version? Not as a rewrite — port the same four checks into the skill's sections. Use the skill where you want the fuller walkthrough and pre-launch checklist, and the rule where you want a silent, always-on ban on a narrow set of files.
Sources
- Stripe Docs, Webhooks — handle duplicate events (at-least-once delivery, dedupe guidance)
- AgenticKit, Cursor rules for Stripe & billing codebases (the four-rule version of the same checks)
- AgenticKit, Stripe billing skill (the installed SKILL.md this post annotates)
Written by Rakshit Yadav. Published 2026-10-29, last updated 2026-10-29.
Related Tools & Agents
Install the full Stripe billing skill
AgenticKit writes this SKILL.md to both .claude/skills/ and .cursor/skills/, plus the /stripe-billing command that runs the checklist for you.
See the Stripe billing skill →