Stripe Webhook Testing

Stripe Webhook Testing Skill

This skill should be used when the user wants to test Stripe webhooks locally during development.

Prerequisites

• Stripe CLI installed (brew install stripe/stripe-cli/stripe on macOS)
• Backend server running on port 3000
• Stripe test mode API keys configured in .env

Setup Process

Step 1: Ensure Webhook Endpoint Exists

The backend must have a webhook endpoint at /api/stripe/webhook. Verify this in:

• backend/src/main.rs - route definition
• backend/src/handlers/stripe_handlers.rs - handler implementation

Step 2: Start Backend Server

Ensure the backend is running:

cd backend && cargo run

The server must be running before starting Stripe CLI forwarding.

Step 3: Start Stripe CLI Forwarding

Run the following command to forward webhooks to localhost:

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

The CLI will output a webhook secret starting with whsec_....

Step 4: Configure Webhook Secret

1. Copy the webhook secret from the CLI output
2. Add or update STRIPE_WEBHOOK_SECRET in backend/.env:

   STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxx
   

3. Restart the backend server to pick up the new secret

Step 5: Trigger Test Events

Use Stripe CLI to trigger test webhook events:

# Subscription events
stripe trigger customer.subscription.created
stripe trigger customer.subscription.updated
stripe trigger customer.subscription.deleted

# Checkout events
stripe trigger checkout.session.completed

# Invoice events
stripe trigger invoice.paid
stripe trigger invoice.payment_failed

Step 6: Verify in Logs

Check backend console output for:

• "Stripe webhook received"
• "Stripe signature header found"
• "Stripe event verified successfully"
• Processing messages for specific event types

Supported Webhook Events

The backend currently handles:

• customer.subscription.created - New subscription activated
• customer.subscription.updated - Subscription modified
• customer.subscription.deleted - Subscription cancelled
• checkout.session.completed - Checkout completed

Troubleshooting

• Signature verification failed: Ensure STRIPE_WEBHOOK_SECRET matches the secret from stripe listen
• Endpoint not found: Verify backend is running on port 3000
• Events not triggering: Run stripe listen first, then trigger events in a new terminal