Configuring Stripe Webhook for Direct API Integration

Why Direct API Integration?

Before (v1.x):

• ❌ Required Firebase Stripe Extension
• ❌ Needed Cloud Functions
• ❌ Complex setup
• ❌ Limited control

Now (v2.2):

• ✅ Direct Stripe API calls
• ✅ Custom Next.js webhook handler
• ✅ No Firebase extensions needed
• ✅ Full TypeScript support
• ✅ Complete control over payment flow

Step 1: Add Stripe API Keys to .env.local

1. Go to your Stripe Dashboard (opens in a new tab)
2. Click Developers → API Keys
3. Copy your Publishable key and Secret key
4. Add them to your .env.local file:

# Stripe Configuration
NEXT_PUBLIC_PUBLISHABLE_KEY=pk_test_your_publishable_key_here
STRIPE_SECRET_KEY=sk_test_your_secret_key_here

Step 2: Configure Webhook for Development

Install Stripe CLI

macOS:

brew install stripe/stripe-cli/stripe

Windows: Download from https://stripe.com/docs/stripe-cli (opens in a new tab)

Login to Stripe

stripe login

Forward Webhooks to Local Server

stripe listen --forward-to localhost:3000/api/stripe/webhook

This will output a webhook signing secret (starts with whsec_). Copy it and add to .env.local:

STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here

Step 3: Configure Webhook for Production

Create Production Webhook Endpoint

1. Go to Stripe Dashboard (opens in a new tab) → Developers → Webhooks
2. Click Add endpoint
3. Enter your production URL:

   https://yourdomain.com/api/stripe/webhook

Select Events to Listen For

Select these essential events:

Required Events:

• ✅ checkout.session.completed
• ✅ customer.subscription.created
• ✅ customer.subscription.updated
• ✅ customer.subscription.deleted
• ✅ invoice.payment_succeeded
• ✅ invoice.payment_failed

Optional Events:

• customer.created
• customer.updated
• invoice.upcoming

Copy Webhook Signing Secret

1. After creating the endpoint, click on it
2. Click Reveal under "Signing secret"
3. Copy the secret (starts with whsec_)
4. Add it to your production environment variables

Step 4: Test Your Webhook

Start Development Server

# Terminal 1: Start Next.js
npm run dev
 
# Terminal 2: Start Stripe webhook forwarding
stripe listen --forward-to localhost:3000/api/stripe/webhook

Test Checkout Flow

1. Go to http://localhost:3000/Signup and create an account
2. Navigate to http://localhost:3000/Dashboard/subscribe
3. Select a subscription plan
4. Use Stripe test card: 4242 4242 4242 4242
   • Expiry: Any future date
   • CVC: Any 3 digits
   • ZIP: Any 5 digits
5. Complete checkout

Verify Webhook Events

In Terminal 2 (where stripe listen is running), you should see:

✔ Received event: checkout.session.completed
✔ Received event: customer.subscription.created
✔ Received event: invoice.payment_succeeded

Check Firestore

1. Go to Firebase Console → Firestore Database
2. Navigate to customers/{userId}/subscriptions
3. You should see the subscription data

How It Works

SaaSavant uses a custom webhook handler at /api/stripe/webhook that:

1. ✅ Verifies webhook signature for security
2. ✅ Handles subscription events in real-time
3. ✅ Updates Firestore with subscription data
4. ✅ Manages customer records automatically
5. ✅ Provides full TypeScript type safety

No Firebase extensions or Cloud Functions required!

Troubleshooting

Webhook Not Receiving Events

Development:

• ✅ Check stripe listen is running
• ✅ Verify webhook secret in .env.local
• ✅ Ensure dev server is running on port 3000

Production:

• ✅ Verify webhook endpoint URL is correct
• ✅ Check webhook secret matches production environment
• ✅ Review Stripe Dashboard → Webhooks for error logs

Subscription Not Updating

1. Check webhook events in Stripe Dashboard
2. Verify Firestore security rules allow writes
3. Check server logs for errors
4. Ensure customer document exists in Firestore

Test Cards

• Success: 4242 4242 4242 4242
• Decline: 4000 0000 0000 0002
• 3D Secure: 4000 0025 0000 3155