Home › Products › Webhooks Done Right (for Stripe)
Webhooks Done Right (for Stripe)
Most Stripe webhook bugs come from the same few mistakes: verifying a parsed body instead of the raw one, using the wrong whsec_ secret, fulfilling an order twice when an event is retried, or returning a 500 for events you don't handle.
This skill teaches Claude Code or Cursor to avoid them. It includes reference endpoints for Express/TypeScript and Flask/Python, an atomic idempotency store, a Postgres schema and signed test fixtures.
Who it's for
Developers adding Stripe payments to a Node or Python app, and anyone stuck on "No signatures found matching the expected signature".
What's tested
- 22 automated tests (11 Node, 11 Python), all passing, plus a clean TypeScript typecheck
- The tests cover rules 1 to 5 in the skill: raw body, correct secret, replay window, idempotency on event.id, status codes
- Fixtures are signed locally, then checked with the real Stripe libraries (stripe-node 19.x, stripe-python 16.x)
What isn't tested
- Live deliveries from Stripe and the Stripe CLI (both need a Stripe account)
- Rules 6 to 9 (respond quickly, event ordering, fulfilment events, API version) are guidance, not covered by tests
- The Postgres schema in templates/ is not run by the tests (they use SQLite)
What's in the download
- SKILL.md: instructions your agent follows
- node/: Express + TypeScript reference endpoint with tests
- python/: Flask reference endpoint with tests
- fixtures/: sample Stripe events
- templates/schema.sql: Postgres idempotency table
- TEST-REPORT.md, LICENSE.txt, REFUND.txt
Requirements
Node 20+ or Python 3.10+. You don't need a Stripe account to run the tests.
How to use it
Copy the folder to .claude/skills/webhooks-done-right-for-stripe/ (Claude Code), or point a Cursor rule at SKILL.md. Then ask your agent to "add a Stripe webhook endpoint" or "fix my Stripe signature errors".