# ✅ Stripe Webhook Setup Complete

## 🎯 What Changed

### 1. New command: `pnpm dev:stripe`

**Start Stripe webhook tunnel in one command:**

```bash
# Terminal 2
pnpm dev:stripe
```

This runs: `stripe listen --forward-to localhost:3001/api/billing/webhook`

### 2. Updated `.env` comments

**Before:**
```bash
# Local dev: Run `stripe listen --forward-to localhost:3000/api/billing/webhook`
```

**After:**
```bash
# ⚠️  Local dev: Start webhook tunnel first → `pnpm dev:stripe` (runs in parallel with backend)
# ⚠️  Then copy the webhook secret (whsec_...) displayed in terminal and paste it here
```

### 3. Fixed port number

**Corrected:** `localhost:3000` → `localhost:3001` (matches actual backend port)

### 4. Removed duplicate URLs

Cleaned up duplicate `CHECKOUT_SUCCESS_URL` and `CHECKOUT_CANCEL_URL` entries in `.env`

---

## 🚀 New Workflow

### Starting the app

**Terminal 1 - Main dev:**
```bash
pnpm dev
```

**Terminal 2 - Stripe webhooks (optional):**
```bash
pnpm dev:stripe
```

When Terminal 2 displays:
```
> Ready! Your webhook signing secret is whsec_abc123...
```

Copy `whsec_abc123...` and add to `apps/api/.env`:
```bash
STRIPE_WEBHOOK_SECRET=whsec_abc123...
```

Then restart Terminal 1 (Ctrl+C → `pnpm dev`).

---

## 📚 Updated Documentation

**Files updated:**
- ✅ `package.json` - Added `dev:stripe` script
- ✅ `apps/api/.env` - Updated comments + fixed port + removed duplicates
- ✅ `README.md` - Added `pnpm dev:stripe` command + fixed port
- ✅ `docs/STRIPE_QUICKSTART.md` - New workflow with `pnpm dev:stripe`
- ✅ `docs/STRIPE_SETUP.md` - Updated webhook section
- ✅ `QUICKSTART.md` - Created comprehensive quick start guide

---

## ✅ Checklist

**For testing Stripe webhooks locally:**

- [ ] Backend running (`pnpm dev` in Terminal 1)
- [ ] Stripe CLI installed (`brew install stripe/stripe-cli/stripe`)
- [ ] Logged in to Stripe (`stripe login`)
- [ ] Webhook tunnel running (`pnpm dev:stripe` in Terminal 2)
- [ ] Webhook secret copied to `apps/api/.env`
- [ ] Backend restarted

**Test webhook:**
```bash
stripe trigger checkout.session.completed
```

**Expected logs:**
```
[Billing] Webhook received: checkout.session.completed
[Billing] User subscription updated
```

---

## 🎓 Quick Reference

| Command | What it does |
|---------|--------------|
| `pnpm dev` | Start frontend (5173) + backend (3001) |
| `pnpm dev:stripe` | Start Stripe webhook tunnel |
| `stripe trigger checkout.session.completed` | Test webhook event |
| `node scripts/test-stripe-config.mjs` | Verify Stripe configuration |

---

**All set! Stripe webhooks are now easy to start with `pnpm dev:stripe`. 🎉**
