webhook-security

What this skill does

# webhook-security

## Instructions

This skill provides comprehensive webhook security patterns for payment integrations (Stripe, PayPal, and other providers). It covers signature verification, replay attack prevention, event logging, idempotency, and local testing workflows.

### 1. Webhook Signature Verification

Implement cryptographic signature verification to authenticate webhook requests:

**Why Signature Verification Matters:**
- Prevents attackers from forging webhook events
- Ensures events actually come from the payment provider
- Required for PCI compliance in production
- Protects against man-in-the-middle attacks

**Setup Process:**
```bash
# Generate and configure webhook endpoint with signature verification
bash /home/gotime2022/.claude/plugins/marketplaces/ai-dev-marketplace/plugins/payments/skills/webhook-security/scripts/setup-webhook-endpoint.sh stripe
```

**Verification Algorithm (Stripe):**
1. Extract timestamp and signature from webhook headers
2. Construct signed payload: `timestamp.raw_body`
3. Compute HMAC-SHA256 hash using webhook secret
4. Compare computed signature with received signature
5. Verify timestamp is within tolerance (5 minutes default)

### 2. Replay Attack Prevention

Protect against replay attacks where attackers resend captured webhook events:

**Defense Mechanisms:**
- **Timestamp Validation:** Reject events older than 5 minutes
- **Event ID Tracking:** Store processed event IDs to prevent duplicates
- **Signature Verification:** Ensures event hasn't been tampered with
- **Idempotency Keys:** Safe to process same event multiple times

**Implementation:**
```python
# Use the signature verification script
python /home/gotime2022/.claude/plugins/marketplaces/ai-dev-marketplace/plugins/payments/skills/webhook-security/scripts/verify-signature.py
```

### 3. Event Logging and Auditing

Log all webhook events for debugging, compliance, and dispute resolution:

**What to Log:**
- Raw webhook payload (for signature re-verification)
- Event type and ID
- Timestamp received
- Processing status (success, failure, retry)
- Error messages if processing failed
- User/account associated with event

**Template Usage:**
```python
# Use event logger template for database storage
cat /home/gotime2022/.claude/plugins/marketplaces/ai-dev-marketplace/plugins/payments/skills/webhook-security/templates/event_logger.py
```

### 4. Local Webhook Testing

Test webhooks locally before deploying to production:

**Using Stripe CLI:**
```bash
# Forward webhooks to local development server
bash /home/gotime2022/.claude/plugins/marketplaces/ai-dev-marketplace/plugins/payments/skills/webhook-security/scripts/test-webhook-locally.sh
```

**Testing Workflow:**
1. Install Stripe CLI (`stripe` command)
2. Login to your Stripe account
3. Forward webhooks to localhost
4. Trigger test events from Stripe Dashboard or CLI
5. Verify signature verification works
6. Check event logging and processing

### 5. Webhook Secret Management

Securely manage webhook signing secrets:

**CRITICAL SECURITY RULE:**
```bash
# ✅ CORRECT - Never hardcode secrets
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here

# ❌ WRONG - Never commit real secrets
STRIPE_WEBHOOK_SECRET=whsec_1234567890abcdef...  # DON'T DO THIS
```

**Generate Webhook Secret:**
```bash
# Get webhook secret for your endpoint
bash /home/gotime2022/.claude/plugins/marketplaces/ai-dev-marketplace/plugins/payments/skills/webhook-security/scripts/generate-webhook-secret.sh
```

**Secret Rotation:**
- Rotate webhook secrets quarterly
- Update all endpoints when rotating
- Test new secret before deactivating old one
- Store in environment variables, never in code

### 6. Error Handling and Retries

Handle webhook processing failures gracefully:

**Retry Logic:**
- Payment providers retry failed webhooks automatically
- Return 200 OK only after successful processing
- Return 500/503 for temporary failures (triggers retry)
- Return 400 for permanent failures (stops retries)

**Template Usage:**
```python
# Use retry handler template
cat /home/gotime2022/.claude/plugins/marketplaces/ai-dev-marketplace/plugins/payments/skills/webhook-security/templates/retry_handler.py
```

**Best Practices:**
- Make webhook handlers idempotent (safe to retry)
- Process events asynchronously (queue for background jobs)
- Respond quickly (< 5 seconds) to avoid timeouts
- Store events before processing (persist first, process later)

## Examples

### Example 1: Stripe Subscription Webhook with Full Security

Complete implementation with signature verification, logging, and idempotency:

```bash
# 1. Set up webhook endpoint with security
bash /home/gotime2022/.claude/plugins/marketplaces/ai-dev-marketplace/plugins/payments/skills/webhook-security/scripts/setup-webhook-endpoint.sh stripe

# 2. View the complete implementation
cat /home/gotime2022/.claude/plugins/marketplaces/ai-dev-marketplace/plugins/payments/skills/webhook-security/examples/complete-webhook-handler.py

# 3. Test locally before deploying
bash /home/gotime2022/.claude/plugins/marketplaces/ai-dev-marketplace/plugins/payments/skills/webhook-security/scripts/test-webhook-locally.sh

# 4. Deploy to production
# Ensure STRIPE_WEBHOOK_SECRET environment variable is set
# Configure webhook endpoint URL in Stripe Dashboard
```

**Result:** Production-ready webhook handler that:
- Verifies Stripe signatures cryptographically
- Prevents replay attacks via timestamp validation
- Logs all events to database with full audit trail
- Handles retries idempotently (safe to process twice)
- Returns appropriate HTTP status codes

### Example 2: Event Processing with Idempotency

Process payment events safely with duplicate protection:

```python
# Use the event processing example
cat /home/gotime2022/.claude/plugins/marketplaces/ai-dev-marketplace/plugins/payments/skills/webhook-security/examples/event-processing-example.py
```

**Implementation:**
1. Check if event ID already processed (database lookup)
2. If processed, return 200 OK immediately (idempotent)
3. If new, store event to database with "pending" status
4. Process the event (update subscription, send email, etc.)
5. Update event status to "processed"
6. Return 200 OK

**Result:** Safe to receive duplicate events without side effects

### Example 3: Multi-Provider Webhook Handler

Support multiple payment providers with unified security:

```bash
# Set up webhooks for Stripe, PayPal, and Square
for provider in stripe paypal square; do
  bash /home/gotime2022/.claude/plugins/marketplaces/ai-dev-marketplace/plugins/payments/skills/webhook-security/scripts/setup-webhook-endpoint.sh $provider
done
```

**Features:**
- Provider-specific signature verification (different algorithms)
- Unified event logging across providers
- Consistent retry handling
- Single testing workflow for all providers

### Example 4: Complete Testing Workflow

End-to-end webhook testing before production deployment:

```bash
# Use the complete testing example
bash /home/gotime2022/.claude/plugins/marketplaces/ai-dev-marketplace/plugins/payments/skills/webhook-security/examples/webhook-testing-example.sh
```

**Test Scenarios:**
1. Valid signature - Should process successfully
2. Invalid signature - Should reject with 401
3. Expired timestamp - Should reject (replay protection)
4. Duplicate event ID - Should return 200 (idempotent)
5. Malformed payload - Should return 400
6. Processing failure - Should return 500 (triggers retry)

**Result:** High confidence before production deployment

## Requirements

**Environment Variables:**
```bash
# Stripe Configuration
STRIPE_API_KEY=sk_test_your_stripe_key_here
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here

# PayPal Configuration (if using PayPal)
PAYPAL_CLIENT_ID=your_paypal_client_id_here
PAYPAL_CLIENT_SECRET=your_paypal_client_secret_here
PAYPAL_WEBHOOK_ID=your_webhook_id_here

# Database Configuration
DATABASE_URL=postgresql://user:pass@localhost:5432/dbname
```

**Dependencies:**

Python (F