šØ EXECUTION NOTICE FOR CLAUDE
When you invoke this command via SlashCommand, the system returns THESE INSTRUCTIONS below.
YOU are the executor. This is NOT an autonomous subprocess.
- ā
The phases below are YOUR execution checklist
- ā
YOU must run each phase immediately using tools (Bash, Read, Write, Edit, TodoWrite)
- ā
Complete ALL phases before considering this command done
- ā DON't wait for "the command to complete" - YOU complete it by executing the phases
- ā DON't treat this as status output - it IS your instruction set
Immediately after SlashCommand returns, start executing Phase 0, then Phase 1, etc.
See @CLAUDE.md section "SlashCommand Execution - YOU Are The Executor" for detailed explanation.
Arguments: $ARGUMENTS
Goal: Setup secure Stripe webhook infrastructure with signature verification, event handlers, and debugging capabilities
SECURITY CRITICAL:
- NEVER hardcode webhook secrets
- Use placeholder: STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here
- Always implement signature verification
- Read secrets from environment variables ONLY
Core Principles:
- Security first: Always verify webhook signatures
- Never trust unverified webhook data
- Store webhook events for debugging and replay
- Implement idempotency for webhook processing
Phase 1: Project Discovery
Actions:
- Parse $ARGUMENTS to determine which events to handle
- Verify FastAPI backend: !{bash test -d backend && echo "Found" || echo "Not found"}
- Check Supabase integration: !{bash test -f backend/.env.example && grep -q "SUPABASE" backend/.env.example && echo "Configured" || echo "Missing"}
- Load existing payment routes: @backend/app/api/routes/payments.py
Phase 2: Environment Configuration
Actions:
- Update backend/.env.example with webhook placeholders
- Add STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here
- Add STRIPE_WEBHOOK_TOLERANCE=300
- Verify .gitignore protects: .env, .env.local, .env.development, .env.production
- Add webhook secret to .gitignore if missing
Phase 3: Create Webhook Infrastructure
Task(description="Create webhook infrastructure", subagent_type="payments:webhook-handler-agent", prompt="You are the webhook-handler-agent. Create secure Stripe webhook infrastructure.
SECURITY: Use placeholder STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here
Create backend/app/api/routes/webhooks.py with:
- POST /api/webhooks/stripe endpoint
- Stripe signature verification using stripe.Webhook.construct_event()
- Raw request body handling for signature verification
- Event type routing for: payment_intent.succeeded, payment_intent.payment_failed, customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, invoice.payment_succeeded, invoice.payment_failed
- Return 400 for invalid signatures
- Store ALL events in webhook_events table
- Implement idempotency: check event_id, skip duplicates
- Comprehensive error handling
Deliverable: backend/app/api/routes/webhooks.py with signature verification and event routing")
Phase 4: Database Schema
Task(description="Create webhook events schema", subagent_type="payments:payments-architect", prompt="You are the payments-architect agent. Create Supabase schema for webhook event storage.
Create supabase/migrations/YYYYMMDDHHMMSS_create_webhook_events.sql with:
- webhook_events table: id uuid, event_id text unique, event_type text, payload jsonb, status text, error_message text, processed_at timestamp, created_at timestamp, updated_at timestamp
- Indexes: event_id unique, event_type, status, created_at
- RLS policies: service role full access, anon/authenticated no access
- Helper functions: get_unprocessed_events(), mark_event_processed(event_id), get_events_by_type(event_type)
Deliverable: Migration file with complete schema and indexes")
Phase 5: Event Handlers
Task(description="Implement event handlers", subagent_type="payments:webhook-handler-agent", prompt="You are the webhook-handler-agent. Create event handler functions for Stripe webhooks.
Create backend/app/services/webhook_handlers.py with handlers for:
- handle_payment_intent_succeeded: Update payment status, send confirmation, update subscription
- handle_payment_intent_failed: Update payment status, send notification, trigger retry
- handle_subscription_created: Create subscription record, update user status, send welcome email
- handle_subscription_updated: Update subscription, handle plan changes, notify user
- handle_subscription_deleted: Mark cancelled, set cancellation date, send confirmation
- handle_invoice_payment_succeeded: Record payment, update billing date, send receipt
- handle_invoice_payment_failed: Record failure, update retry schedule, send notification
Each handler must:
- Accept full Stripe event object
- Extract data safely
- Update database atomically
- Handle errors gracefully
- Return success/failure status
- Log all actions
Deliverable: webhook_handlers.py with all event handlers and error handling")
Phase 6: Testing Setup
Task(description="Setup webhook testing", subagent_type="payments:stripe-integration-agent", prompt="You are the stripe-integration-agent. Create local webhook testing infrastructure.
Create:
- docs/webhooks/LOCAL_TESTING.md with Stripe CLI installation, webhook forwarding, testing workflow
- backend/scripts/test-webhooks.sh to trigger all webhook events and verify processing
- Testing checklist: signature verification, invalid signatures rejected, all event types handled, database records created, idempotency works
Include Stripe CLI commands for local testing and event triggering.
Deliverable: LOCAL_TESTING.md, test-webhooks.sh, testing checklist")
Phase 7: Production Documentation
Actions:
- Create docs/webhooks/PRODUCTION_SETUP.md documenting:
- Webhook endpoint registration in Stripe Dashboard
- Production webhook URL format
- Required webhook events to enable
- Webhook secret retrieval from Stripe
- Environment variable configuration
- Webhook endpoint testing in production
- Monitoring and alerting setup
- Include security reminders: HTTPS only, never log secrets, verify all signatures, monitor patterns, alert on failures
Phase 8: Error Handling
Actions:
- Add retry logic for transient failures with exponential backoff
- Implement dead letter queue for failed webhooks
- Create admin endpoint to replay failed webhooks
- Set up alerts for repeated failures
- Document error scenarios and responses
Phase 9: Validation
Actions:
- Run webhook tests: !{bash cd backend && python -m pytest tests/test_webhooks.py -v}
- Verify signature validation works
- Test all event handlers
- Check database records created correctly
- Verify idempotency handles duplicates
- Test error scenarios: invalid signatures, malformed payloads
Phase 10: Summary
Actions:
- Display created files: webhooks.py, webhook_handlers.py, migration file, .env.example, LOCAL_TESTING.md, PRODUCTION_SETUP.md, test-webhooks.sh
- Show configuration checklist: endpoint created, signature verification implemented, event handlers created, database schema, env vars configured, testing documented, production setup documented, error handling implemented
- Provide next steps:
- Copy backend/.env.example to backend/.env
- Get webhook secret: stripe listen --print-secret
- Add to backend/.env: STRIPE_WEBHOOK_SECRET=whsec_...
- Start backend: uvicorn app.main:app --reload
- Forward webhooks: stripe listen --forward-to localhost:8000/api/webhooks/stripe
- Test events: stripe trigger payment_intent.succeeded
- Verify in Supabase webhook_events table
- Production deployment: register endpoint in Stripe Dashboard, add production secret, deploy backend, test webhook, monitor events