Create Webhook Handler

Automatically generate production-ready webhook endpoints with signature verification, idempotency, retry handling, event processing, and comprehensive security measures for reliable third-party integrations.

When to Use This Command

Use /create-webhook-handler when you need to:

• Receive real-time events from external services (Stripe, GitHub, Slack)
• Build event-driven architectures with external triggers
• Implement payment processing notifications
• Handle CI/CD pipeline events
• Process incoming data from IoT devices
• Create serverless event receivers

DON'T use this when:

• Building internal service communication (use message queues)
• Need guaranteed ordering (webhooks are best-effort)
• Handling large payloads (>10MB typically)
• Bidirectional communication needed (consider WebSockets)

Design Decisions

This command implements signature-based verification as the primary approach because:

• Industry-standard security practice (HMAC-SHA256)
• Prevents replay attacks with timestamp validation
• Ensures message integrity and authenticity
• Widely supported by webhook providers
• Simple to implement and verify
• Minimal overhead for validation

Alternative considered: OAuth token validation

• More complex setup required
• Additional network calls for validation
• Higher latency
• Recommended for user-authenticated webhooks

Alternative considered: mTLS (mutual TLS)

• Strongest security option
• Complex certificate management
• Not widely supported
• Recommended for enterprise B2B integrations

Prerequisites

Before running this command:

1. Webhook URL endpoint defined
2. Shared secret or signing key from provider
3. Event types to handle documented
4. Database for idempotency tracking
5. Queue system for async processing (optional)

Implementation Process

Step 1: Create Webhook Endpoint

Define secure POST endpoint with proper routing and middleware.

Step 2: Implement Signature Verification

Validate webhook authenticity using HMAC signatures.

Step 3: Add Idempotency Handling

Prevent duplicate processing of retried events.

Step 4: Route Events to Handlers

Dispatch events to appropriate processing functions.

Step 5: Configure Monitoring

Set up logging, metrics, and alerting for webhook health.

Output Format

The command generates:

• webhooks/handlers/ - Event-specific handler functions
• webhooks/middleware/ - Signature verification, rate limiting
• webhooks/routes.js - Webhook endpoint definitions
• webhooks/processors/ - Async event processors
• webhooks/schemas/ - Event validation schemas
• config/webhooks.json - Provider configurations
• tests/webhooks/ - Integration tests with mock events

Code Examples

Example 1: Multi-Provider Webhook System with Express

// webhooks/middleware/signature.js
const crypto = require('crypto');
const { WebhookError } = require('../errors');

class SignatureVerifier {
    constructor(config) {
        this.providers = config.providers;
        this.timestampTolerance = config.timestampTolerance || 300; // 5 minutes
    }

    // Stripe signature verification
    verifyStripe(payload, signature, secret) {
        const elements = signature.split(',');
        const timestamp = elements.find(e => e.startsWith('t=')).substring(2);
        const signatures = elements
            .filter(e => e.startsWith('v1='))
            .map(e => e.substring(3));
…

Example 2: Serverless Webhook Handler with AWS Lambda

# webhook_handler.py - AWS Lambda function
import json
import hmac
import hashlib
import time
import boto3
from typing import Dict, Any, Optional
from dataclasses import dataclass
from enum import Enum

dynamodb = boto3.resource('dynamodb')
sqs = boto3.client('sqs')
sns = boto3.client('sns')

class WebhookProvider(Enum):
    STRIPE = "stripe"
    GITHUB = "github"
    SLACK = "slack"
…

Example 3: Testing Webhook Handlers

// tests/webhook.test.js
const request = require('supertest');
const crypto = require('crypto');
const app = require('../app');
const Redis = require('ioredis-mock');

describe('Webhook Handler Tests', () => {
    let redis;

    beforeEach(() => {
        redis = new Redis();
    });

    describe('Stripe Webhooks', () => {
        const secret = 'whsec_test_secret';

        function generateStripeSignature(payload, secret) {
            const timestamp = Math.floor(Date.now() / 1000);
…

Error Handling

Configuration Options

Security Options

• signatureAlgorithm: HMAC-SHA256, HMAC-SHA512
• timestampTolerance: Maximum age of webhook (seconds)
• ipAllowlist: Restrict to provider IPs
• rateLimits: Per-provider rate limiting

Processing Options

• asyncProcessing: Queue events for background processing