Estimate: Add Stripe Webhook Handling

Problem Description

We run a SaaS application built with Next.js 14 (App Router) and Supabase. We already have Stripe Checkout integrated — customers can subscribe and pay through our checkout flow using the official Stripe SDK. However, we currently have no webhook handling: when a payment succeeds, a subscription is canceled, or an invoice fails, we have no way to react on the backend.

The team wants to add proper Stripe webhook handling so the app can process events like checkout.session.completed, invoice.payment_failed, and customer.subscription.deleted. This should update subscription status in our database and trigger relevant internal actions.

Output Specification

Produce a complete estimation document and save it to estimate.md. The estimate should cover all the work needed to implement Stripe webhook handling, broken down into manageable pieces with time estimates for an AI coding agent (not a human developer).

Input Files

The following files describe the current state of the project. Extract them before beginning.

=============== FILE: inputs/package.json =============== { "name": "saas-app", "version": "2.1.0", "dependencies": { "next": "14.2.5", "react": "18.3.1", "react-dom": "18.3.1", "stripe": "^16.2.0", "@supabase/supabase-js": "^2.45.0", "@supabase/ssr": "^0.4.0", "tailwindcss": "^3.4.0", "zod": "^3.23.0", "next-auth": "^4.24.0" }, "devDependencies": { "typescript": "^5.5.0", "@types/react": "^18.3.0", "vitest": "^2.0.0", "playwright": "^1.45.0" } }

=============== FILE: inputs/file-tree.txt =============== src/ ├── app/ │ ├── layout.tsx │ ├── page.tsx │ ├── (auth)/ │ │ ├── login/page.tsx │ │ └── signup/page.tsx │ ├── dashboard/ │ │ ├── page.tsx │ │ ├── settings/page.tsx │ │ └── billing/page.tsx │ └── api/ │ ├── auth/[...nextauth]/route.ts │ └── checkout/route.ts ├── components/ │ ├── ui/ (shadcn components) │ ├── PricingTable.tsx │ └── SubscriptionBadge.tsx ├── lib/ │ ├── stripe.ts │ ├── supabase/ │ │ ├── client.ts │ │ └── server.ts │ └── utils.ts ├── types/ │ └── index.ts tests/ ├── unit/ │ └── lib/stripe.test.ts └── e2e/ └── checkout.spec.ts

=============== FILE: inputs/stripe.ts =============== import Stripe from 'stripe';

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, { apiVersion: '2024-06-20', typescript: true, });

export async function createCheckoutSession(priceId: string, customerId: string) { return stripe.checkout.sessions.create({ customer: customerId, line_items: [{ price: priceId, quantity: 1 }], mode: 'subscription', success_url: ${process.env.NEXT_PUBLIC_URL}/dashboard?checkout=success, cancel_url: ${process.env.NEXT_PUBLIC_URL}/dashboard/billing, }); }