Stripe Webhook Events

File: stripe-webhook-events.md

Loading documentation...

# Stripe Webhook Events for Subscription Payments

## Required Webhook Events

You need to configure these webhook events in your Stripe Dashboard to handle subscription payments properly.

### 1. **Subscription Events**

#### `customer.subscription.created`
- **When**: New subscription is created
- **Purpose**: Update subscription status and period dates
- **Handler**: `handleCustomerSubscriptionCreated()`

#### `customer.subscription.updated`
- **When**: Subscription details are modified
- **Purpose**: Update subscription status, period dates, cancellation info
- **Handler**: `handleCustomerSubscriptionUpdated()`

#### `customer.subscription.deleted`
- **When**: Subscription is cancelled/deleted
- **Purpose**: Mark subscription as ended
- **Handler**: `handleCustomerSubscriptionDeleted()`

#### `customer.subscription.trial_will_end`
- **When**: Trial period is about to end (3 days before)
- **Purpose**: Send notifications to users
- **Handler**: `handleCustomerSubscriptionTrialWillEnd()`

### 2. **Invoice Events**

#### `invoice.payment_succeeded`
- **When**: Payment for invoice is successful
- **Purpose**: Record payment, update subscription status
- **Handler**: `handleInvoicePaymentSucceeded()`

#### `invoice.payment_failed`
- **When**: Payment for invoice fails
- **Purpose**: Record failed payment, update subscription status
- **Handler**: `handleInvoicePaymentFailed()`

#### `invoice.payment_action_required`
- **When**: Payment requires additional action (3D Secure, etc.)
- **Purpose**: Update subscription status to incomplete
- **Handler**: `handleInvoicePaymentActionRequired()`

### 3. **Payment Method Events**

#### `payment_method.attached`
- **When**: New payment method is added to customer
- **Purpose**: Track payment method changes
- **Handler**: `handlePaymentMethodAttached()`

#### `payment_method.detached`
- **When**: Payment method is removed from customer
- **Purpose**: Track payment method changes
- **Handler**: `handlePaymentMethodDetached()`

### 4. **Customer Events**

#### `customer.updated`
- **When**: Customer information is updated
- **Purpose**: Sync customer data changes
- **Handler**: `handleCustomerUpdated()`

#### `customer.deleted`
- **When**: Customer is deleted
- **Purpose**: Handle customer deletion
- **Handler**: `handleCustomerDeleted()`

### 5. **Charge Events**

#### `charge.succeeded`
- **When**: Charge is successful
- **Purpose**: Track successful charges
- **Handler**: `handleChargeSucceeded()`

#### `charge.failed`
- **When**: Charge fails
- **Purpose**: Track failed charges
- **Handler**: `handleChargeFailed()`

#### `charge.refunded`
- **When**: Charge is refunded
- **Purpose**: Update payment status to refunded
- **Handler**: `handleChargeRefunded()`

### 6. **Dispute Events**

#### `charge.dispute.created`
- **When**: Customer disputes a charge
- **Purpose**: Handle chargebacks/disputes
- **Handler**: `handleChargeDisputeCreated()`

#### `charge.dispute.closed`
- **When**: Dispute is resolved
- **Purpose**: Handle dispute resolution
- **Handler**: `handleChargeDisputeClosed()`

## How to Configure in Stripe Dashboard

### 1. **Access Webhook Settings**
1. Go to [Stripe Dashboard](https://dashboard.stripe.com)
2. Navigate to **Developers** → **Webhooks**
3. Click **Add endpoint**

### 2. **Configure Endpoint**
- **Endpoint URL**: `https://yourdomain.com/api/webhook/stripe`
- **Events to send**: Select the events listed above
- **API Version**: Use the latest stable version

### 3. **Get Webhook Secret**
1. After creating the webhook, click on it
2. Go to **Signing secret**
3. Click **Reveal** and copy the secret
4. Add to your `.env` file: `STRIPE_WEBHOOK_SECRET=whsec_...`

### 4. **Test Webhooks**
1. In the webhook details, click **Send test webhook**
2. Select an event type and click **Send test webhook**
3. Check your Laravel logs to ensure it's working

## Webhook Security

### 1. **Verify Webhook Signatures**
Laravel Cashier automatically verifies webhook signatures using your `STRIPE_WEBHOOK_SECRET`.

### 2. **Idempotency**
Webhook handlers should be idempotent (safe to run multiple times). The current implementation handles this by:
- Using `update()` instead of `create()` for existing records
- Checking if records exist before creating new ones

### 3. **Error Handling**
- All webhook handlers return HTTP 200 to acknowledge receipt
- Errors are logged for debugging
- Failed webhooks are retried by Stripe

## Testing Webhooks

### 1. **Using Stripe CLI**
```bash
# Install Stripe CLI
stripe listen --forward-to localhost:8000/api/webhook/stripe

# In another terminal, trigger events
stripe trigger customer.subscription.created
stripe trigger invoice.payment_succeeded
```

### 2. **Using Stripe Dashboard**
1. Go to webhook details
2. Click **Send test webhook**
3. Select event type and send

### 3. **Check Logs**
```bash
# View Laravel logs
tail -f storage/logs/laravel.log

# Filter webhook logs
grep "Webhook" storage/logs/laravel.log
```

## Important Notes

### 1. **Event Order**
- Events may arrive out of order
- Always check current state before updating
- Use timestamps to handle race conditions

### 2. **Retry Logic**
- Stripe retries failed webhooks automatically
- Implement idempotent handlers
- Log all webhook events for debugging

### 3. **Database Updates**
- Update subscription status based on webhook events
- Record all payments in `subscription_payments` table
- Keep subscription dates in sync

### 4. **Error Monitoring**
- Monitor webhook failures in Stripe Dashboard
- Set up alerts for webhook errors
- Check Laravel logs regularly

## Example Webhook Flow

1. **User subscribes** → `customer.subscription.created`
2. **Payment succeeds** → `invoice.payment_succeeded`
3. **Subscription active** → Status updated to "active"
4. **Payment recorded** → Entry in `subscription_payments` table
5. **Next billing** → `invoice.payment_succeeded` (recurring)
6. **User cancels** → `customer.subscription.updated` (canceled)
7. **Subscription ends** → `customer.subscription.deleted`

This webhook setup ensures your subscription system stays in sync with Stripe and handles all payment scenarios properly.

Stripe Webhook Events

Stripe Webhook Events

📝 Page Notes

Add New Note