Webhook validation patterns with signature verification, event logging, and testing tools. Use when implementing webhooks, validating webhook signatures, securing payment webhooks, testing webhook endpoints, preventing replay attacks, or when user mentions webhook security, Stripe webhooks, signature verification, webhook testing, or event validation.
Limited to specific tools
Additional assets for this skill
This skill is limited to using the following tools:
README.mdexamples/complete-webhook-handler.pyexamples/event-processing-example.pyexamples/webhook-testing-example.shscripts/generate-webhook-secret.shscripts/setup-webhook-endpoint.shscripts/test-webhook-locally.shscripts/verify-signature.pytemplates/event_logger.pytemplates/retry_handler.pytemplates/webhook_handler.pytemplates/webhook_test.pyThis 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.
Implement cryptographic signature verification to authenticate webhook requests:
Why Signature Verification Matters:
Setup Process:
# 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):
timestamp.raw_bodyProtect against replay attacks where attackers resend captured webhook events:
Defense Mechanisms:
Implementation:
# Use the signature verification script
python /home/gotime2022/.claude/plugins/marketplaces/ai-dev-marketplace/plugins/payments/skills/webhook-security/scripts/verify-signature.py
Log all webhook events for debugging, compliance, and dispute resolution:
What to Log:
Template Usage:
# 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
Test webhooks locally before deploying to production:
Using Stripe CLI:
# 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:
stripe command)Securely manage webhook signing secrets:
CRITICAL SECURITY RULE:
# ✅ 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:
# 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:
Handle webhook processing failures gracefully:
Retry Logic:
Template Usage:
# Use retry handler template
cat /home/gotime2022/.claude/plugins/marketplaces/ai-dev-marketplace/plugins/payments/skills/webhook-security/templates/retry_handler.py
Best Practices:
Complete implementation with signature verification, logging, and idempotency:
# 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:
Process payment events safely with duplicate protection:
# 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:
Result: Safe to receive duplicate events without side effects
Support multiple payment providers with unified security:
# 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:
End-to-end webhook testing before production deployment:
# 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:
Result: High confidence before production deployment
Environment Variables:
# 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 (FastAPI):
fastapi - Web framework for webhook endpointsstripe - Stripe Python SDKsqlalchemy - Database ORM for event loggingpydantic - Data validationpython-dotenv - Environment variable managementhttpx - HTTP client for webhook testingDevelopment Tools:
stripe-cli - Local webhook testing (download from Stripe)ngrok or localtunnel - Expose localhost for testingpytest - Testing frameworkrequests - HTTP client for manual testingDatabase Setup:
Required table for event logging:
CREATE TABLE webhook_events (
id SERIAL PRIMARY KEY,
event_id VARCHAR(255) UNIQUE NOT NULL,
event_type VARCHAR(100) NOT NULL,
provider VARCHAR(50) NOT NULL,
payload JSONB NOT NULL,
signature VARCHAR(255) NOT NULL,
status VARCHAR(50) DEFAULT 'pending',
error_message TEXT,
created_at TIMESTAMP DEFAULT NOW(),
processed_at TIMESTAMP
);
CREATE INDEX idx_event_id ON webhook_events(event_id);
CREATE INDEX idx_status ON webhook_events(status);
Payment Provider Setup:
Stripe:
customer.subscription.updated)STRIPE_WEBHOOK_SECRET environment variablePayPal:
PAYPAL_WEBHOOK_ID environment variableCRITICAL: Never Hardcode Webhook Secrets
# ✅ CORRECT - Use environment variables
export STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here
# ✅ CORRECT - Read from environment in code
import os
webhook_secret = os.getenv("STRIPE_WEBHOOK_SECRET")
if not webhook_secret:
raise ValueError("STRIPE_WEBHOOK_SECRET not set")
# ❌ WRONG - Never hardcode secrets
webhook_secret = "whsec_1234567890abcdef..." # DON'T DO THIS
Always Verify Signatures:
Prevent Replay Attacks:
Protect Webhook Endpoints:
Event Logging:
Idempotency:
Error Handling:
Stripe Subscription Events:
customer.subscription.created - New subscriptioncustomer.subscription.updated - Plan change, renewalcustomer.subscription.deleted - Cancellationinvoice.payment_succeeded - Successful paymentinvoice.payment_failed - Failed paymentStripe Payment Events:
payment_intent.succeeded - One-time payment successpayment_intent.payment_failed - Payment failurecharge.refunded - Refund processedcharge.dispute.created - Chargeback disputePayPal Events:
PAYMENT.SALE.COMPLETED - Payment completedBILLING.SUBSCRIPTION.CREATED - New subscriptionBILLING.SUBSCRIPTION.CANCELLED - Subscription cancelledCUSTOMER.DISPUTE.CREATED - Dispute openedSignature Verification Failing:
Events Not Reaching Endpoint:
Duplicate Events Being Processed:
Plugin: payments Version: 1.0.0 Category: Security Skill Type: Webhook Security