stripe-webhook-testing - SKILL.md Agent Skill

name: stripe-webhook-testing description: Set up Stripe CLI to forward webhooks to local development server for testing Stripe integrations

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

Copy the webhook secret from the CLI output

Add or update STRIPE_WEBHOOK_SECRET in backend/.env:

STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxx

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