Skip to content
SlashClone
DiscoverUse in ClaudeSubmit a link
Sign in
Made by@shipcheck

Stripe webhook hardening

@shipcheck/stripe-webhook-hardening

Find your Stripe webhook handlers and harden them: verify the Stripe-Signature header, use the raw body, keep the signing secret in env, process each event once, reject bad signatures with 400, and fulfill orders from the webhook rather than the success page. Reads your code and proposes diffs; never calls Stripe.

SkillDevOpsv1.0.0 (latest)Tested
Use in Claude Save Like Clone Comment
Activity
New: be the first to try it
  1. 1---
  2. 2name: stripe-webhook-hardening
  3. 3description: Review and fix Stripe webhook handlers so payments cannot be faked or double counted. Checks signature verification with the Stripe-Signature header, raw request body, signing secret in env, idempotency on event.id, 400 on bad signatures, event type filtering, edge runtime support, and that fulfillment happens in the webhook rather than on the success page. Use when the user adds Stripe Checkout or subscriptions, asks "is my Stripe webhook secure", sees "No signatures found matching the expected signature", gets duplicate orders, or before launching paid features.
  4. 4license: MIT
  5. 5---
  6. 6
  7. 7# Stripe webhook hardening
  8. 8
  9. 9A Stripe webhook is a public URL that grants paid access. If it skips the signature check, anyone can post a fake "payment succeeded" event. If it is not idempotent, a Stripe retry gives double credits. This skill finds the handlers, checks them, and proposes small, specific diffs.
  10. 10
  11. 11## When to use
  12. 12
  13. 13- After adding Stripe Checkout, Payment Links, subscriptions, or Connect.
  14. 14- "Is my webhook secure?", "signature verification failed", "users got charged once but credited twice".
  15. 15- Before turning on live mode.
  16. 16
  17. 17## Steps
  18. 18
  19. 191. **Scan.**
  20. 20
  21. 21 ```bash
  22. 22 node scripts/webhook-scan.mjs . --json out/webhook-scan.json --md out/webhook-scan.md
  23. 23 ```
  24. 24
  25. 25 If it finds 0 handlers, search the code for `stripe-signature`, `constructEvent`, and `checkout.session.completed`, and ask the user which route their Stripe dashboard points to.
  26. 26
  27. 272. **Read every handler file in full.** The scan is a pointer, not the verdict. Confirm each finding against the code and check what the scan cannot:
  28. 28 - **Fulfillment source:** is access granted on the success page (reading `session_id` from the URL) instead of in the webhook? The success page is user-controlled. It may show "thanks", but only the webhook grants access.
  29. 29 - **Trusting metadata blindly:** amounts and prices should come from the Stripe event or a Stripe API lookup, never from client-sent values.
  30. 30 - **Slow work before responding:** long jobs (emails, AI calls) should be queued so the handler returns 2xx within a few seconds, or Stripe retries.
  31. 31 - **Event coverage:** subscriptions need `customer.subscription.updated` and `.deleted`, and `invoice.payment_failed`, or cancelled users keep access.
  32. 323. **Report** using the format below. High first.
  33. 334. **Propose fixes as diffs**, one finding at a time, and apply each only after the user says yes. Use the patterns below for their framework.
  34. 345. **If idempotency needs a table,** write a new migration (for example `create table processed_events (id text primary key, created_at timestamptz default now())`) and show it. The user applies it.
  35. 356. **Test plan.** Tell the user to run `stripe listen --forward-to localhost:3000/api/webhooks/stripe` and `stripe trigger checkout.session.completed` themselves, then resend the same event from the dashboard to confirm it is processed once.
  36. 36
  37. 37## Fix patterns
  38. 38
  39. 39Next.js App Router:
  40. 40
  41. 41```ts
  42. 42export async function POST(req: Request) {
  43. 43 const body = await req.text(); // raw body, never req.json()
  44. 44 const sig = req.headers.get("stripe-signature") ?? "";
  45. 45 let event: Stripe.Event;
  46. 46 try {
  47. 47 event = stripe.webhooks.constructEvent(body, sig, webhookSecret); // webhookSecret from STRIPE_WEBHOOK_SECRET
  48. 48 } catch {
  49. 49 return new Response("Invalid signature", { status: 400 });
  50. 50 }
  51. 51 // insert event.id into processed_events; on conflict return 200 and stop
  52. 52}
  53. 53```
  54. 54
  55. 55Express: register `express.raw({ type: "application/json" })` on the webhook route, before `app.use(express.json())`. Edge or Supabase Edge Functions: `await stripe.webhooks.constructEventAsync(body, sig, secret, undefined, Stripe.createSubtleCryptoProvider())`.
  56. 56
  57. 57## Output format
  58. 58
  59. 59```markdown
  60. 60# Stripe webhooks: <project>
  61. 61Handlers: 1 | High 2 | Medium 1 | Low 0
  62. 62
  63. 63## app/api/webhooks/stripe/route.ts
  64. 64- HIGH signature: no constructEvent. Anyone can fake a paid checkout. Fix: diff 1.
  65. 65- HIGH raw-body: uses req.json(). Fix: diff 1.
  66. 66- MEDIUM idempotency: retries double the credits. Fix: diff 2 plus migration.
  67. 67- Fulfillment: success page also grants access (app/success/page.tsx:14). Fix: diff 3.
  68. 68```
  69. 69
  70. 70## Guardrails
  71. 71
  72. 72- Never call the Stripe API, create webhook endpoints, or roll secrets. Tell the user where to do it in the dashboard.
  73. 73- Never print or paste a signing secret or API key. If one is hardcoded, report the file and line only, and say it must be rolled.
  74. 74- Never "fix" a failing signature by removing verification or by switching to test mode.
  75. 75- Use test mode for every test you suggest. Live mode is the user's call.
Sign in to comment on a line