Stripe Local Development Setup

Overview

This guide explains how to test Stripe webhooks locally while your production webhook points to your Cloud Run backend.

Current Setup

Production (Cloud Run)

• Webhook URL: https://capitolscope-api-1074255918859.us-west1.run.app/api/v1/stripe/webhook
• Success URL: https://capitolscope.chrislawrence.ca/dashboard?payment=success
• Cancel URL: https://capitolscope.chrislawrence.ca/premium?payment=cancelled

Local Development

• Webhook URL: localhost:8000/api/v1/stripe/webhook (forwarded via Stripe CLI)
• Success URL: http://localhost:3000/dashboard?payment=success
• Cancel URL: http://localhost:3000/premium?payment=cancelled

Local Development Workflow

1. Start Local Development

# Start your local Docker containers
capitol-build

# In a separate terminal, start Stripe webhook forwarding
capitol-stripe-webhook

2. What the Stripe CLI Does

The capitol-stripe-webhook command:

• Listens for webhook events from your Stripe sandbox
• Forwards them to localhost:8000/api/v1/stripe/webhook
• Provides a webhook signing secret for local testing
• Shows real-time webhook events in the terminal

3. Environment Variables for Local Dev

Make sure your local .env file has:

# Local development URLs
STRIPE_SUCCESS_URL=http://localhost:3000/dashboard?payment=success
STRIPE_CANCEL_URL=http://localhost:3000/premium?payment=cancelled
STRIPE_WEBHOOK_ENDPOINT=http://localhost:8000/api/v1/stripe/webhook

Switching Between Local and Production

For Local Testing

1. Start local containers: capitol-build
2. Start webhook forwarding: capitol-stripe-webhook
3. Use local URLs in your frontend

For Production Testing

1. Deploy to Cloud Run: capitol-deploy-backend
2. Update environment variables: capitol-update-env
3. Use production URLs in your frontend

Stripe Dashboard Configuration

Current Setup (Production)

• Webhook Endpoint: https://capitolscope-api-1074255918859.us-west1.run.app/api/v1/stripe/webhook
• Events: All subscription and payment events

For Local Testing

• Webhook Endpoint: http://localhost:8000/api/v1/stripe/webhook (via Stripe CLI)
• Events: Same events, but forwarded locally

Commands Reference

# Local development
capitol-build                    # Start local containers
capitol-stripe-webhook          # Forward Stripe webhooks locally
capitol-logs                    # View container logs

# Production deployment
capitol-deploy-backend          # Deploy backend to Cloud Run
capitol-update-env              # Update environment variables
capitol-deploy-frontend         # Deploy frontend to Cloud Run

Troubleshooting

Webhook Not Receiving Events

1. Check if Stripe CLI is running: capitol-stripe-webhook
2. Verify local containers are running: capitol-logs
3. Check webhook endpoint is accessible: curl http://localhost:8000/api/v1/stripe/webhook

Production Webhook Errors

1. Check Cloud Run logs in Google Cloud Console
2. Verify environment variables are set: capitol-update-env
3. Test webhook endpoint: curl https://capitolscope-api-1074255918859.us-west1.run.app/api/v1/stripe/webhook

Migration to Production

When you're ready to go live:

1. Update Stripe dashboard webhook URL to production
2. Update environment variables to production URLs
3. Deploy both frontend and backend
4. Test with real payments (small amounts first)

Notes

• Stripe CLI automatically handles webhook signing for local development
• You don't need to change the webhook URL in Stripe dashboard for local testing
• The CLI creates a temporary webhook endpoint that forwards to your local server
• All webhook events are logged in the CLI terminal for debugging