Next.js Stripe Billing Webhooks Cursor Rules Template

Overview

This Cursor Rules Template provides a Next.js oriented Cursor rules configuration for securely handling Stripe Billing webhooks in a server-side API route. It covers the Next.js stack, Stripe webhook signature verification, idempotent processing, and a clean architectural layout suitable for production deployments with Cursor AI.

When to Use These Cursor Rules

• Setting up a Stripe Billing webhook in a Next.js project using API Routes
• Implementing secure webhook verification and idempotent event processing
• Enforcing a maintainable project structure with clear separation of concerns
• Automating tests for webhook handlers and deployment-time checks

Copyable .cursorrules Configuration

framework: nextjs
stack: stripe-billing-webhooks
role: Cursor AI assistant for Next.js Stripe webhooks
context: Implement a secure Stripe webhook endpoint for Next.js API Routes using TypeScript.
codeStyle: typescript eslint prettier
architecture:
  - Endpoint: src/pages/api/stripeWebhook.ts
  - Processor: src/services/webhookProcessor.ts
  - DB: src/lib/db.ts
security:
  - STRIPE_WEBHOOK_SECRET from env
  - verifyStripeSignature(payload, signature, secret)
  - disableCSRF for webhook route
  - avoid logging sensitive payloads
idempotency:
  - stripe_event_id in stripe_events
validation:
  - only process known events
db:
  - table stripe_events (id, stripe_event_id, type, livemode, created_at, payload_hash, processed)

Recommended Project Structure

apps/
  nextjs-stripe-webhooks/
    src/
      pages/
        api/
          stripeWebhook.ts
      lib/
        stripe.ts
        db.ts
        webhookValidator.ts
      services/
        webhookProcessor.ts
    tests/
      webhook.test.ts
      integration/
        webhook.integration.test.ts

Core Engineering Principles

• Security by default: verify Stripe signatures and keep secrets in env
• Idempotent processing to handle retries
• Clear separation of concerns and testability
• Type-safe code with TypeScript
• Infrastructure as code for deployment and testing

Code Construction Rules

• Endpoint path must be /api/stripe/webhooks
• Verify Stripe signature using the Stripe library for signature verification
• Persist events to a stripe_events table with a unique stripe_event_id
• Do not expose raw Stripe payloads to clients
• Use a separate processor for business logic

Security and Production Rules

• Load STRIPE_WEBHOOK_SECRET from environment; never commit to code
• Validate and signature-check every webhook event
• Enforce strict time-bound processing and idempotency
• Log minimal metadata; avoid sensitive payloads
• Use server-side API Routes; avoid client exposure

Testing Checklist

• Unit tests for signature verification and event parsing
• Integration tests using Stripe CLI to send live events
• End-to-end tests for webhook delivery and idempotency
• Linting and type checks in CI

Common Mistakes to Avoid

• Assuming payload is trusted without verification
• Ignoring idempotency leading to duplicate processing
• Logging full webhook payloads or secrets
• Over-fetching or slow external calls in webhook handler

FAQ

What stack does this Cursor Rules Template cover?

The template targets Next.js with Stripe Billing webhooks, using API Routes in TypeScript, Stripe signature verification, and a small DB layer to ensure idempotent processing.

How do I use the copyable .cursorrules block?

Copy the code block into your repository as a starting point for Cursor AI to tailor your Next.js Stripe webhook integration. It defines architecture, security, and testing expectations in a portable format.

Does this enforce webhook signature verification?

Yes. The rules emphasize Stripe webhook signature verification, strict event validation, and avoiding processing unknown events unless whitelisted.

Where should I place the webhook endpoint in a Next.js project?

Place it under src/pages/api/stripeWebhook.ts (or equivalent) to handle server-side events securely and keep client code separate.

How is idempotency achieved?

Events are written to a stripe_events table with a unique stripe_event_id; duplicate events are ignored based on the uniqueness constraint and an idempotent processor.