# Task: Implement Secure Webhook Endpoint with Signature Verification ## Template Variables Before starting implementation, define these values: - **`{{SERVICE_NAME}}`**: The webhook provider service name (e.g., "Stripe", "Notion", "GitHub", "Shopify", "Twilio", "Slack", "Beehiiv") - **`{{WEBHOOK_ENDPOINT_URL}}`**: The API endpoint path for receiving webhooks (e.g., `/api/webhooks/stripe`, `/webhooks/notion`, `/api/v1/webhooks/github`) - **`{{WEBHOOK_SECRET_ENV_VAR}}`**: The environment variable name for the webhook signing secret (e.g., `STRIPE_WEBHOOK_SECRET`, `NOTION_WEBHOOK_SECRET`, `WEBHOOK_SECRET`) **Example Configurations:**

Stripe Integration

``` SERVICE_NAME: Stripe WEBHOOK_ENDPOINT_URL: /api/webhooks/stripe WEBHOOK_SECRET_ENV_VAR: STRIPE_WEBHOOK_SECRET ```

Notion Integration

``` SERVICE_NAME: Notion WEBHOOK_ENDPOINT_URL: /api/webhooks/notion WEBHOOK_SECRET_ENV_VAR: NOTION_WEBHOOK_SECRET ```

GitHub Integration

``` SERVICE_NAME: GitHub WEBHOOK_ENDPOINT_URL: /api/webhooks/github WEBHOOK_SECRET_ENV_VAR: GITHUB_WEBHOOK_SECRET ```

Beehiiv Integration

``` SERVICE_NAME: Beehiiv WEBHOOK_ENDPOINT_URL: /api/webhooks/beehiiv WEBHOOK_SECRET_ENV_VAR: BEEHIIV_WEBHOOK_SECRET ```

Generic/Custom Service

``` SERVICE_NAME: YourService WEBHOOK_ENDPOINT_URL: /webhooks/your-service WEBHOOK_SECRET_ENV_VAR: WEBHOOK_SECRET ```

--- ## How to Use This Prompt 1. **Replace the template variables** throughout this prompt with your specific values 2. **Find and replace** all instances: - `{{SERVICE_NAME}}` → Your service name (e.g., "Stripe") - `{{WEBHOOK_ENDPOINT_URL}}` → Your endpoint path (e.g., "/api/webhooks/stripe") - `{{WEBHOOK_SECRET_ENV_VAR}}` → Your env var name (e.g., "STRIPE_WEBHOOK_SECRET") 3. **Provide the customized prompt** to your AI coding assistant 4. The AI will implement a webhook endpoint specifically configured for your service --- **Your Role:** You are a backend security engineer specializing in webhook integrations and cryptographic verification. You have expertise in implementing secure webhook endpoints, handling HMAC-based signature verification, preserving raw request bodies for cryptographic operations, and protecting backend systems from unauthorized webhook requests and replay attacks. ## Context Webhooks are HTTP callbacks that allow third-party services to send real-time event notifications to your application. However, without proper verification, your webhook endpoints are vulnerable to unauthorized requests, data tampering, and replay attacks. This implementation establishes a secure webhook endpoint that verifies the authenticity of incoming webhook requests using cryptographic signature verification for **{{SERVICE_NAME}}**. The signature verification process ensures that webhook requests originate from the expected service provider and that the payload has not been tampered with during transmission. This is a critical security layer for any application that receives webhook notifications from payment processors, communication platforms, version control systems, or any external service provider. ## Requirements ### Core Webhook Endpoint Structure - **Endpoint Definition**: Create a dedicated webhook endpoint route for your service provider - **HTTP Method**: Accept POST requests (standard for webhooks) - **Raw Body Preservation**: Preserve the raw request body buffer before any parsing occurs - **Request Headers**: Extract signature-related headers sent by the webhook provider - **Response Handling**: Return appropriate HTTP status codes to acknowledge receipt ### Signature Verification Methods Choose the appropriate verification method based on your webhook provider: **Standard HMAC SHA-256 Verification** (Most Common): - Used by: Stripe, GitHub, Shopify, Twilio, many others - Requires: Webhook signing secret from provider - Process: Generate HMAC signature from raw body and compare with provided signature - Implementation: Use timing-safe comparison to prevent timing attacks **Svix Standard Verification** (Advanced): - Used by: Services using the Svix webhook infrastructure - Requires: Webhook signing secret from provider - Features: Built-in timestamp validation, multi-signature support, replay attack prevention - Implementation: Use the Svix webhook verification library **Provider-Specific Formats**: - Each provider may have unique signature header names and generation methods - Follow the provider's official documentation for exact implementation details ### Security Requirements - **Timing-Safe Comparison**: Use cryptographic comparison methods that prevent timing attacks - **Replay Attack Prevention**: Validate timestamp headers to reject old webhook requests - **Environment Variables**: Store webhook signing secrets in environment variables, never in code - **HTTPS Only**: Only accept webhooks over HTTPS in production environments - **Error Handling**: Handle verification failures gracefully without exposing internal details - **Rate Limiting**: Implement rate limiting to prevent webhook flooding attacks ### Request Processing Flow 1. **Receive Request**: Accept incoming POST request to webhook endpoint 2. **Extract Raw Body**: Preserve the raw request body buffer (critical for signature verification) 3. **Extract Headers**: Get signature and timestamp headers from the request 4. **Verify Signature**: Perform cryptographic verification using the appropriate method 5. **Validate Timestamp**: Check that the webhook is not too old (prevent replay attacks) 6. **Process Event**: If verification succeeds, process the webhook payload 7. **Respond**: Return 200 OK to acknowledge successful receipt ### Error Handling and Logging - **Verification Failures**: Log failed verification attempts with relevant details - **Missing Signatures**: Return 400 Bad Request when signature headers are missing - **Invalid Timestamps**: Reject webhooks outside the acceptable time window - **Processing Errors**: Handle payload processing errors separately from verification errors - **Structured Logging**: Include timestamp, provider, event type, and verification status ## Implementation ### Step 1: Review {{SERVICE_NAME}} Webhook Documentation 1. Locate **{{SERVICE_NAME}}'s** webhook signature verification documentation 2. Identify the following information: - Signature header name (e.g., `stripe-signature`, `x-hub-signature-256`, `x-notion-signature`) - Timestamp header name (if applicable) - Signature generation algorithm (usually HMAC SHA-256) - Webhook signing secret location in **{{SERVICE_NAME}}** dashboard - Recommended timestamp tolerance (typically 5 minutes) 3. Note any **{{SERVICE_NAME}}-specific** verification requirements or library recommendations 4. Check if **{{SERVICE_NAME}}** uses standard HMAC, Svix format, or a custom signature scheme ### Step 2: Configure Environment Variables 1. Add **{{SERVICE_NAME}}** webhook signing secret to your environment configuration file: - Node.js/Express: `.env` file - Python/Django: `.env` or `settings.py` - Ruby/Rails: `.env` or `credentials.yml.enc` - Go: `.env` or environment-specific config 2. Create the environment variable **{{WEBHOOK_SECRET_ENV_VAR}}**: ```bash # .env file {{WEBHOOK_SECRET_ENV_VAR}}=whsec_yoursecrethere ``` **Examples for different services:** ```bash # Stripe STRIPE_WEBHOOK_SECRET=whsec_abc123... # GitHub GITHUB_WEBHOOK_SECRET=ghp_xyz789... # Notion NOTION_WEBHOOK_SECRET=secret_abc123... # Generic WEBHOOK_SECRET=your_secret_here ``` 3. Load environment variables in your application entry point 4. Verify **{{WEBHOOK_SECRET_ENV_VAR}}** is not committed to version control (check `.gitignore`) 5. Document **{{WEBHOOK_SECRET_ENV_VAR}}** in your README with instructions for obtaining it from **{{SERVICE_NAME}}** ### Step 3: Set Up Raw Body Preservation **Critical Requirement**: Signature verification requires the raw request body exactly as received #### For Express.js (JavaScript/TypeScript): ```javascript // Apply raw body parsing ONLY to webhook routes app.use( '{{WEBHOOK_ENDPOINT_URL}}', express.raw({ type: 'application/json' }) ); // The raw body will be available as req.body (Buffer type) ``` #### For Next.js API Routes: ```javascript export const config = { api: { bodyParser: false, // Disable body parsing }, }; // Read raw body manually in the handler async function getRawBody(req) { const chunks = []; for await (const chunk of req) { chunks.push(chunk); } return Buffer.concat(chunks); } ``` #### For Django (Python): ```python # Access raw body before parsing raw_body = request.body # bytes # Parse JSON after verification import json payload = json.loads(raw_body) ``` #### For Ruby on Rails: ```ruby # Read raw body raw_body = request.body.read # Parse JSON after verification payload = JSON.parse(raw_body) ``` #### For Flask (Python): ```python raw_body = request.get_data() # bytes payload = json.loads(raw_body) ``` #### For FastAPI (Python): ```python from fastapi import Request @app.post("/webhooks") async def webhook(request: Request): raw_body = await request.body() # bytes # Verify signature using raw_body ``` #### For Go (net/http): ```go import "io/ioutil" rawBody, err := ioutil.ReadAll(r.Body) if err != nil { // Handle error } // Close and recreate body for further processing r.Body = ioutil.NopCloser(bytes.NewBuffer(rawBody)) ``` **Key Point**: The raw body must be preserved exactly as received - no parsing, trimming, or modification before verification. ### Step 4: Create the Webhook Endpoint Route 1. Create a new route file for **{{SERVICE_NAME}}** webhooks following your framework's conventions 2. Define the webhook endpoint path as **{{WEBHOOK_ENDPOINT_URL}}** 3. Set up the route to handle POST requests 4. Extract necessary headers from the request (consult **{{SERVICE_NAME}}** documentation) 5. Validate that required headers are present before proceeding **Example structures by framework**: **Express.js**: ```javascript // Route definition for {{SERVICE_NAME}} router.post('{{WEBHOOK_ENDPOINT_URL}}', async (req, res) => { const signature = req.headers['signature-header-name']; // Check {{SERVICE_NAME}} docs const timestamp = req.headers['timestamp-header-name']; // If applicable // Continue with verification... }); ``` **Django**: ```python @csrf_exempt # Webhooks don't have CSRF tokens def webhook_view(request): if request.method == 'POST': signature = request.headers.get('Signature-Header-Name') # Continue with verification... ``` **Rails**: ```ruby skip_before_action :verify_authenticity_token # Skip CSRF for webhooks def webhook signature = request.headers['Signature-Header-Name'] # Continue with verification... end ``` ### Step 5: Implement Standard HMAC SHA-256 Verification **For {{SERVICE_NAME}}** (if using standard HMAC signatures): #### JavaScript/TypeScript: ```javascript const crypto = require('crypto'); // Extract signature (check {{SERVICE_NAME}} documentation for header name) const signature = req.headers['signature-header-name']; // Get webhook secret from environment const webhookSecret = process.env.{{WEBHOOK_SECRET_ENV_VAR}}; // Generate expected signature const expectedSignature = crypto .createHmac('sha256', webhookSecret) .update(rawBody) // Must be raw Buffer or string .digest('hex'); // Or 'base64' - check {{SERVICE_NAME}} docs // Timing-safe comparison const isValid = crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expectedSignature) ); if (!isValid) { console.error('[{{SERVICE_NAME}}] Invalid webhook signature'); return res.status(400).json({ error: 'Invalid signature' }); } ``` #### Python: ```python import hmac import hashlib import os # Get webhook secret from environment webhook_secret = os.environ.get('{{WEBHOOK_SECRET_ENV_VAR}}') # Generate expected signature expected_signature = hmac.new( webhook_secret.encode(), raw_body, hashlib.sha256 ).hexdigest() # Or .hexdigest() - check {{SERVICE_NAME}} docs # Timing-safe comparison is_valid = hmac.compare_digest(signature, expected_signature) if not is_valid: print(f'[{{SERVICE_NAME}}] Invalid webhook signature') return JsonResponse({'error': 'Invalid signature'}, status=400) ``` #### Ruby: ```ruby require 'openssl' # Get webhook secret from environment webhook_secret = ENV['{{WEBHOOK_SECRET_ENV_VAR}}'] # Generate expected signature expected_signature = OpenSSL::HMAC.hexdigest( 'SHA256', webhook_secret, raw_body ) # Timing-safe comparison is_valid = Rack::Utils.secure_compare(signature, expected_signature) unless is_valid puts "[{{SERVICE_NAME}}] Invalid webhook signature" render json: { error: 'Invalid signature' }, status: 400 end ``` #### Go: ```go import ( "crypto/hmac" "crypto/sha256" "encoding/hex" "crypto/subtle" "os" ) // Get webhook secret from environment webhookSecret := os.Getenv("{{WEBHOOK_SECRET_ENV_VAR}}") // Generate expected signature mac := hmac.New(sha256.New, []byte(webhookSecret)) mac.Write(rawBody) expectedSignature := hex.EncodeToString(mac.Sum(nil)) // Timing-safe comparison isValid := subtle.ConstantTimeCompare( []byte(signature), []byte(expectedSignature), ) == 1 if !isValid { log.Printf("[{{SERVICE_NAME}}] Invalid webhook signature") http.Error(w, "Invalid signature", http.StatusBadRequest) return } ``` ### Step 6: Add Timestamp Validation (Replay Attack Prevention) If your provider includes timestamps in headers: ```javascript // Extract timestamp from header const timestamp = parseInt(req.headers['timestamp-header-name']); // Get current time const currentTime = Math.floor(Date.now() / 1000); // Calculate time difference const timeDifference = currentTime - timestamp; // Set tolerance (5 minutes = 300 seconds) const TOLERANCE = 300; if (timeDifference > TOLERANCE) { return res.status(400).json({ error: 'Webhook timestamp too old - possible replay attack' }); } if (timeDifference < -TOLERANCE) { return res.status(400).json({ error: 'Webhook timestamp from future - possible attack' }); } ``` ### Step 7: Implement Svix Standard Verification (Alternative) **For {{SERVICE_NAME}}** (if using Svix webhook infrastructure): #### JavaScript/TypeScript: ```bash npm install svix ``` ```javascript const { Webhook } = require('svix'); // Get webhook secret from environment const webhookSecret = process.env.{{WEBHOOK_SECRET_ENV_VAR}}; const webhook = new Webhook(webhookSecret); try { const payload = webhook.verify(rawBody, { 'svix-id': req.headers['svix-id'], 'svix-timestamp': req.headers['svix-timestamp'], 'svix-signature': req.headers['svix-signature'], }); console.log('[{{SERVICE_NAME}}] Webhook signature verified successfully'); // Verification successful, payload is verified and parsed } catch (err) { console.error('[{{SERVICE_NAME}}] Svix verification failed:', err.message); return res.status(400).json({ error: 'Webhook verification failed' }); } ``` #### Python: ```bash pip install svix ``` ```python from svix.webhooks import Webhook import os # Get webhook secret from environment webhook_secret = os.environ.get('{{WEBHOOK_SECRET_ENV_VAR}}') webhook = Webhook(webhook_secret) try: payload = webhook.verify(raw_body, { 'svix-id': request.headers.get('svix-id'), 'svix-timestamp': request.headers.get('svix-timestamp'), 'svix-signature': request.headers.get('svix-signature'), }) print(f'[{{SERVICE_NAME}}] Webhook signature verified successfully') # Verification successful except Exception as e: print(f'[{{SERVICE_NAME}}] Svix verification failed: {str(e)}') return JsonResponse({'error': 'Webhook verification failed'}, status=400) ``` **Benefits**: Svix library handles timestamp validation and replay attack prevention automatically. ### Step 8: Handle Verification Results #### On Successful Verification: ```javascript // Parse payload (if not already parsed) const payload = JSON.parse(rawBody.toString()); // Extract event type (check {{SERVICE_NAME}} payload structure) const eventType = payload.type || payload.event || payload.action; // Log successful receipt console.log(`[{{SERVICE_NAME}}] Received webhook event: ${eventType}`); // Process webhook event await processWebhookEvent(eventType, payload); // Return 200 OK immediately return res.status(200).json({ received: true }); ``` #### On Verification Failure: ```javascript console.error('[{{SERVICE_NAME}}] Signature verification failed', { timestamp: new Date().toISOString(), // Do NOT log the full payload or secrets }); return res.status(400).json({ error: 'Webhook verification failed' }); ``` #### On Missing Signature: ```javascript if (!signature) { console.warn('[{{SERVICE_NAME}}] Missing signature header'); return res.status(400).json({ error: 'Missing signature header' }); } ``` ### Step 9: Implement Webhook Event Processing 1. **Create event type mapping**: ```javascript async function processWebhookEvent(eventType, payload) { switch (eventType) { case 'payment.succeeded': await handlePaymentSucceeded(payload); break; case 'payment.failed': await handlePaymentFailed(payload); break; case 'customer.created': await handleCustomerCreated(payload); break; default: console.log(`[Webhook] Unhandled event type: ${eventType}`); } } ``` 2. **Implement event handlers**: ```javascript async function handlePaymentSucceeded(payload) { try { const paymentId = payload.data.id; const amount = payload.data.amount; // Update database await db.payments.update({ where: { id: paymentId }, data: { status: 'succeeded', amount } }); // Send confirmation email await sendPaymentConfirmation(payload.data.customer_email); console.log(`[Webhook] Payment processed: ${paymentId}`); } catch (error) { console.error('[Webhook] Error processing payment:', error); throw error; // Re-throw to trigger retry } } ``` 3. **Implement idempotency** (prevent duplicate processing): ```javascript async function processWebhookEvent(eventType, payload) { const eventId = payload.id; // Check if already processed const existingEvent = await db.webhookEvents.findUnique({ where: { eventId } }); if (existingEvent) { console.log(`[Webhook] Event already processed: ${eventId}`); return; // Skip processing, but still return 200 } // Process event await handleEvent(eventType, payload); // Mark as processed await db.webhookEvents.create({ data: { eventId, eventType, processedAt: new Date() } }); } ``` ### Step 10: Add Comprehensive Logging ```javascript // Log webhook receipt console.log('[{{SERVICE_NAME}}] Received webhook', { eventType: eventType, eventId: payload.id, timestamp: new Date().toISOString() }); // Log verification result console.log('[{{SERVICE_NAME}}] Signature verification:', { status: isValid ? 'SUCCESS' : 'FAILED' }); // Log processing result console.log('[{{SERVICE_NAME}}] Event processed', { eventType: eventType, eventId: payload.id, duration: `${Date.now() - startTime}ms` }); // Log errors with context console.error('[{{SERVICE_NAME}}] Processing failed', { eventType: eventType, eventId: payload.id, error: error.message, stack: error.stack }); ``` ### Step 11: Configure Webhook in {{SERVICE_NAME}} Dashboard 1. Log into your **{{SERVICE_NAME}}** dashboard 2. Navigate to webhook settings (consult **{{SERVICE_NAME}}** documentation for exact location): - **Common locations**: Settings → Webhooks, Developer Settings, API Settings, Integrations 3. Add your webhook endpoint URL: - **Production**: `https://yourdomain.com{{WEBHOOK_ENDPOINT_URL}}` - **Development**: Use tunneling tool (see Step 12) - **Example**: `https://api.myapp.com{{WEBHOOK_ENDPOINT_URL}}` 4. Select event types to receive from **{{SERVICE_NAME}}** (subscribe only to what you need) 5. Copy the webhook signing secret provided by **{{SERVICE_NAME}}** 6. Add the secret to your environment configuration as **{{WEBHOOK_SECRET_ENV_VAR}}**: ```bash {{WEBHOOK_SECRET_ENV_VAR}}=the_secret_from_service_dashboard ``` 7. Save the webhook configuration in **{{SERVICE_NAME}}** 8. Test webhook from **{{SERVICE_NAME}}** dashboard (most providers have "Send test event" button) ### Step 12: Test Webhook Endpoint #### Using Provider CLI Tools: **Stripe CLI**: ```bash # Install Stripe CLI brew install stripe/stripe-cli/stripe # Forward webhooks to local endpoint stripe listen --forward-to localhost:5000/api/webhooks/stripe # Trigger test events stripe trigger payment_intent.succeeded ``` **GitHub CLI**: ```bash # Use webhook testing in repository settings # Or use curl with generated signature ``` #### Using Tunneling Tools (for local development): **ngrok**: ```bash # Install ngrok brew install ngrok # Create tunnel to local server (adjust port as needed) ngrok http 5000 # Use the HTTPS URL in {{SERVICE_NAME}} dashboard # Format: https://abc123.ngrok.io{{WEBHOOK_ENDPOINT_URL}} # Example: https://abc123.ngrok.io/api/webhooks/stripe ``` **localtunnel**: ```bash # Install localtunnel npm install -g localtunnel # Create tunnel (adjust port as needed) lt --port 5000 # Use the provided URL in {{SERVICE_NAME}} dashboard # Format: https://your-subdomain.loca.lt{{WEBHOOK_ENDPOINT_URL}} ``` #### Manual Testing with curl: ```bash # Set your webhook secret (from {{WEBHOOK_SECRET_ENV_VAR}}) SECRET="your_webhook_secret_here" # Test payload PAYLOAD='{"test":"data"}' # Generate signature manually (adjust algorithm if needed) SIGNATURE=$(echo -n "$PAYLOAD" | \ openssl dgst -sha256 -hmac "$SECRET" | \ awk '{print $2}') # Send test request to {{WEBHOOK_ENDPOINT_URL}} curl -X POST http://localhost:5000{{WEBHOOK_ENDPOINT_URL}} \ -H "Content-Type: application/json" \ -H "X-Signature: $SIGNATURE" \ -d "$PAYLOAD" # Note: Adjust header name (X-Signature) to match {{SERVICE_NAME}}'s requirements ``` #### Test Cases to Verify: 1. **Valid signature** → Should return 200 OK 2. **Invalid signature** → Should return 400 Bad Request 3. **Missing signature** → Should return 400 Bad Request 4. **Expired timestamp** → Should return 400 Bad Request 5. **Malformed JSON** → Should return 400 Bad Request 6. **Duplicate event ID** → Should return 200 OK (idempotency) 7. **Unknown event type** → Should return 200 OK (log and ignore) ## Additional Notes ### Template Variable Reference This prompt uses three template variables that should be replaced before use: 1. **{{SERVICE_NAME}}**: Replace with your webhook provider's name - Used in: Logging messages, comments, error messages - Example: "Stripe", "Notion", "GitHub", "Beehiiv" 2. **{{WEBHOOK_ENDPOINT_URL}}**: Replace with your webhook endpoint path - Used in: Route definitions, middleware configuration, dashboard setup - Example: "/api/webhooks/stripe", "/webhooks/notion" 3. **{{WEBHOOK_SECRET_ENV_VAR}}**: Replace with your environment variable name - Used in: Environment configuration, secret retrieval in code - Example: "STRIPE_WEBHOOK_SECRET", "NOTION_WEBHOOK_SECRET" **Quick Find & Replace:** - Use your text editor's find-and-replace feature - Replace all three variables before sharing with AI - Ensure consistency throughout the entire prompt ### What TO Do (✅) - Preserve raw request body exactly as received before any parsing - Use timing-safe comparison methods for signature validation - Store webhook signing secrets in environment variables - Validate timestamps to prevent replay attacks (5-minute tolerance) - Return 200 OK response quickly (within 5-10 seconds) - Process webhook events asynchronously if they involve long operations - Log all webhook attempts with verification status - Handle verification failures without exposing internal details - Test webhooks thoroughly in development - Use HTTPS endpoints in production - Implement rate limiting on webhook endpoints - Create separate endpoints for different providers - Implement idempotency using event IDs - Document supported event types and required environment variables ### What NOT to Do (❌) - Do NOT parse request body before signature verification - Do NOT use simple string comparison for signatures (timing attack vulnerability) - Do NOT skip timestamp validation (replay attack vulnerability) - Do NOT expose webhook secrets in logs or error messages - Do NOT process payloads that fail verification - Do NOT return detailed error messages about verification failures - Do NOT commit webhook secrets to version control - Do NOT use HTTP endpoints in production - Do NOT assume payloads are always well-formed - Do NOT block response while processing (acknowledge first, process async) - Do NOT ignore verification failures - Do NOT reuse endpoints for multiple providers without identification ### Important Constraints - Raw body preservation is **critical** - any modification breaks verification - Signature verification must occur **before** payload processing - Webhook signing secret must be kept confidential - Endpoints must be publicly accessible (no user authentication) - Most providers require 200 OK within 5-10 seconds or retry - Retries can cause duplicates - implement idempotency - Different providers use different header names and formats - Timestamp tolerance balances security vs reliability (typically 5 minutes) ### Provider-Specific Implementation References #### Stripe: - **Signature Header**: `stripe-signature` - **Format**: `t=timestamp,v1=signature` - **Algorithm**: HMAC SHA-256 - **Library**: `stripe` npm package - **Testing**: Stripe CLI (`stripe listen`) - **Docs**: https://stripe.com/docs/webhooks/signatures #### GitHub: - **Signature Header**: `x-hub-signature-256` - **Format**: `sha256=signature` - **Algorithm**: HMAC SHA-256 - **Testing**: Repository webhook settings - **Docs**: https://docs.github.com/webhooks #### Shopify: - **Signature Header**: `x-shopify-hmac-sha256` - **Format**: Base64-encoded HMAC SHA-256 - **Algorithm**: HMAC SHA-256 - **Testing**: Admin dashboard webhook tester - **Docs**: https://shopify.dev/docs/apps/webhooks #### Twilio: - **Signature Header**: `x-twilio-signature` - **Algorithm**: SHA1 with URL and params - **Library**: Twilio SDK validation utility - **Docs**: https://www.twilio.com/docs/usage/webhooks/webhooks-security #### Slack: - **Signature Header**: `x-slack-signature` - **Timestamp Header**: `x-slack-request-timestamp` - **Algorithm**: HMAC SHA-256 with version prefix - **Docs**: https://api.slack.com/authentication/verifying-requests-from-slack ### Security Best Practices - **HTTPS Only**: Never accept webhooks over HTTP in production - **IP Whitelisting**: Use if provider publishes webhook source IPs - **Rate Limiting**: Prevent webhook flooding attacks - **Secret Rotation**: Periodically rotate webhook secrets - **Monitoring**: Alert on verification failures (possible attacks) - **Idempotency**: Handle duplicate events gracefully - **Input Validation**: Validate payload structure after verification - **Error Isolation**: Don't let webhook errors crash application - **Audit Logging**: Log all attempts for security review ### Troubleshooting Guide **Problem**: Signature verification always fails - **Check**: Raw body is preserved (not parsed) - **Check**: Webhook secret is correct in environment - **Check**: Signature header name matches provider - **Check**: Algorithm matches (SHA-256 vs SHA-512) - **Test**: Use provider's CLI/testing tools **Problem**: Webhook endpoint not receiving requests - **Check**: Endpoint is publicly accessible - **Check**: URL in provider dashboard is correct - **Check**: Firewall allows inbound traffic - **Check**: HTTPS is enabled **Problem**: Timestamps always invalid - **Check**: Server time is synchronized (NTP) - **Check**: Timestamp extraction logic - **Check**: Tolerance window setting - **Check**: Timestamp unit (seconds vs milliseconds) **Problem**: Duplicate event processing - **Cause**: Provider retries on non-200 responses - **Solution**: Return 200 OK quickly - **Solution**: Implement idempotency with event IDs - **Solution**: Use database constraints ### Performance Considerations - Return 200 OK within seconds (acknowledge receipt) - Use job queues for slow processing (Redis, RabbitMQ, SQS) - Implement idempotency with event IDs - Scale webhook endpoints separately if needed - Monitor processing time and optimize handlers - Consider webhook event IDs for deduplication ### Validation Checklist Before deployment, verify: - Webhook endpoint receives POST requests - Raw body is preserved before parsing - Valid signatures pass verification - Invalid signatures are rejected - Missing signatures return 400 - Timestamp validation prevents replay attacks - Secrets stored in environment variables - Event handlers implemented for all types - Errors handled without crashes - Logging captures attempts with details - 200 OK returned within time limit - Provider test webhooks succeed - HTTPS enabled in production - Rate limiting configured - Documentation includes setup instructions