# STRIPE_WEBHOOK_SECRET Configuration Task

## Current Status
**URGENT ACTION REQUIRED** - The $50 app (RateRight v2) has a placeholder Stripe webhook secret in `.env.local`:
```
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here
```

Without the correct webhook signing secret, **Stripe webhook verification fails and payment state updates won't process**.

## What Will Break Without This Fix

### Critical Payment Flow Issues:
1. **Payment status updates won't sync** - When customers complete payments, Stripe can't notify the app
2. **Subscription management fails** - Renewals, cancellations, and upgrades won't be processed
3. **Payment confirmation emails won't send** - Customers won't receive payment receipts
4. **Database payment records stay "pending"** - Payments won't be marked as "succeeded" in your system
5. **Refunds and disputes won't be tracked** - You won't know about chargebacks or refund requests

### Business Impact:
- **Lost revenue** - Payments may appear to fail even when they succeed
- **Customer confusion** - Users pay but don't get service activation
- **Manual intervention required** - You'll need to manually check Stripe dashboard and update records
- **No automated payment processing** - The entire payment flow breaks

## Step-by-Step Instructions for Michael

### Part 1: Find Your Webhook Signing Secret in Stripe Dashboard

**Time: ~3 minutes**

1. **Log in to Stripe Dashboard**
   - Go to: https://dashboard.stripe.com
   - Use your RateRight account credentials

2. **Navigate to Webhooks Section**
   - In the left sidebar, click **"Developers"** (wrench icon)
   - Click **"Webhooks"** in the submenu
   - **Alternative path**: Direct link: https://dashboard.stripe.com/webhooks

3. **Find Your Webhook Endpoint**
   - Look for an endpoint with URL: `https://rivet.rateright.com.au/api/webhooks/stripe`
   - If it doesn't exist, you'll need to create it (see Part 2 below)
   - **Note**: Each endpoint has its own unique signing secret

4. **Get the Signing Secret**
   - Click on your webhook endpoint to view details
   - Look for **"Signing secret"** section
   - Click **"Click to reveal"** to show the secret
   - The secret will look like: `whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
   - **Copy this exact value** (it's 32+ characters starting with `whsec_`)

### Part 2: Create Webhook Endpoint (If Missing)

**Only do this if no endpoint exists for `https://rivet.rateright.com.au/api/webhooks/stripe`**

1. **Create New Endpoint**
   - On the Webhooks page, click **"Add endpoint"** or **"Create an event destination"**
   - Enter these details:
     - **Endpoint URL**: `https://rivet.rateright.com.au/api/webhooks/stripe`
     - **Description**: "RateRight v2 Payment Webhooks"
     - **Events to send**: Select these critical events:
       - `payment_intent.succeeded`
       - `payment_intent.payment_failed`
       - `customer.subscription.created`
       - `customer.subscription.updated`
       - `customer.subscription.deleted`
       - `invoice.paid`
       - `invoice.payment_failed`
       - `charge.refunded`
       - `charge.dispute.created`

2. **Save and Get Secret**
   - Click **"Add endpoint"** or **"Create endpoint"**
   - The signing secret will be displayed (click "Click to reveal")
   - **Copy this exact value**

### Part 3: Update .env.local on the VPS

**Time: ~1 minute**

1. **SSH into your VPS**
   ```bash
   ssh root@134.199.153.159
   ```

2. **Navigate to the app directory**
   ```bash
   cd /home/ccuser/the-50-dollar-app
   ```

3. **Edit the .env.local file**
   ```bash
   nano .env.local
   ```

4. **Find and Replace the Placeholder**
   - Look for this line:
     ```
     STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here
     ```
   - Replace it with your actual secret:
     ```
     STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
     ```
   - **Important**: Keep the exact format, no quotes, no spaces

5. **Save and Exit**
   - Press `Ctrl+X`, then `Y`, then `Enter`

6. **Restart the Application**
   ```bash
   systemctl restart rateright-app
   ```

7. **Verify the Service**
   ```bash
   systemctl status rateright-app
   ```
   - Should show "active (running)"

## Verification Steps

1. **Test Webhook Delivery (Optional but Recommended)**
   - In Stripe Dashboard, go to your webhook endpoint
   - Click **"Send test webhook"**
   - Select `payment_intent.succeeded` event
   - Check if it delivers successfully (should show "Delivered" status)

2. **Make a Test Payment**
   - Go to https://rivet.rateright.com.au
   - Make a test payment (use Stripe test card: 4242 4242 4242 4242)
   - Check if payment status updates correctly in your app

## Troubleshooting

### If Webhooks Still Fail:
1. **Check VPS logs**:
   ```bash
   journalctl -u rateright-app -f
   ```
   - Look for webhook-related errors

2. **Verify Environment Variable**:
   ```bash
   grep STRIPE_WEBHOOK_SECRET /home/ccuser/the-50-dollar-app/.env.local
   ```

3. **Check Stripe Dashboard**:
   - Go to Webhooks → Your endpoint → Events tab
   - Look for failed deliveries and error messages

### Common Issues:
- **Secret format wrong**: Must be exactly `whsec_` followed by 32+ characters
- **Missing events**: Ensure all critical payment events are selected
- **URL incorrect**: Must be `https://rivet.rateright.com.au/api/webhooks/stripe`
- **App not restarted**: Always restart after changing .env.local

## Quick Reference

**Stripe Dashboard Path**: Developers → Webhooks → [Your Endpoint] → "Click to reveal" signing secret

**VPS File**: `/home/ccuser/the-50-dollar-app/.env.local`

**Restart Command**: `systemctl restart rateright-app`

**Current Placeholder**: `whsec_your_webhook_secret_here`

**Expected Format**: `whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`

## Time Estimate
- Finding secret in Stripe: 2-3 minutes
- Updating VPS file: 1 minute
- **Total**: Under 5 minutes

## Priority: HIGH
This is blocking payment processing. Without this fix, customers can pay but won't get service activation, leading to support issues and potential revenue loss.

---

*Last Updated: 2026-02-09*
*Assigned to: Michael*
*Status: Pending - Needs Stripe Dashboard Access*