Webhook Best Practices

// 1. Use Standard Webhooks format
const webhookPayload = {
    id: 'msg_unique_id',       // Required: unique message ID
    type: 'event.type',         // Required: reverse-DNS event type
    timestamp: 'ISO-8601',      // Required: when the event occurred
    data: { /* event data */ }, // Required: the event payload
};

// 2. Include idempotency keys
const idempotentWebhook = {
    idempotencyKey: 'unique_key',
    // Consumer uses this to deduplicate retries
};

// 3. Use reverse-DNS event naming
const eventNames = {
    'com.stripe.payment.succeeded': 'Payment succeeded',
    'com.github.push': 'Push to repository',
    'com.sendgrid.bounce': 'Email bounced',
};

// 1. Always verify HMAC signatures
function verifySignature(rawBody, signatureHeader, secret) {
    const expectedSig = signatureHeader.replace('sha256=', '');
    const computedSig = crypto
        .createHmac('sha256', secret)
        .update(rawBody)
        .digest('hex');

    if (!crypto.timingSafeEqual(
        Buffer.from(computedSig),
        Buffer.from(expectedSig)
    )) {
        throw new Error('Invalid signature');
    }
}

// 2. Validate timestamps for replay prevention
function validateTimestamp(timestampHeader) {
    const age = Date.now() - new Date(timestampHeader).getTime();
    if (Math.abs(age) > 300000) { // 5 minutes
        throw new Error('Webhook too old');
    }
}

// 3. Use HTTPS everywhere
function validateUrl(url) {
    const parsed = new URL(url);
    return parsed.protocol === 'https:';
}

// 4. Rotate secrets regularly (every 90 days)
// 5. Limit retries to prevent infinite delivery attempts
// 6. Rate limit per subscriber

// 1. Acknowledge immediately, process later
app.post('/webhook', (req, res) => {
    // Acknowledge receipt immediately
    res.status(200).send('OK');

    // Process asynchronously
    queue.add('process-webhook', req.body);
});

// 2. Implement exponential backoff with jitter
function getRetryDelay(attempt) {
    const baseDelay = 1000 * Math.pow(2, attempt);
    const jitter = baseDelay * 0.1 * (Math.random() * 2 - 1);
    return Math.min(baseDelay + jitter, 3600000); // Max 1 hour
}

// 3. Dead letter queue for permanent failures
class DLQ {
    async add(webhook, error) {
        await db.insert('webhook_dlq', {
            webhook_id: webhook.id,
            payload: webhook,
            error: error.message,
            failed_at: new Date(),
        });
    }
}

// 4. Monitor delivery success rate
function checkDeliveryHealth() {
    const rate = getSuccessRate('1h');
    if (rate < 0.99) {
        alert('Delivery success rate below 99%');
    }
}

// 1. Provide clear documentation
const webhookDocs = {
    events: [
        {
            name: 'payment.succeeded',
            description: 'Sent when a payment completes successfully',
            schema: { /* JSON Schema */ },
            example: { /* Example payload */ },
        },
    ],
    retry_policy: '5 retries over 9 hours',
    rate_limits: '100 webhooks per minute',
    signature: 'HMAC-SHA256 with webhook secret',
};

// 2. Provide a test mode
async function sendTestWebhook(eventType) {
    const testPayload = generateTestPayload(eventType);
    await sendWebhook(process.env.TEST_ENDPOINT, testPayload);
}

// 3. Provide webhook logs and debugging
app.get('/api/webhooks/logs', async (req, res) => {
    const logs = await getDeliveryLogs(req.query);
    res.json(logs);
});

// 4. Include SDK/client libraries
class WebhookSDK {
    static verify(payload, headers, secret) {
        // Standard verification
    }
    static createSignedPayload(data, secret) {
        // Automatic signing
    }
}

// 1. Health check endpoints
app.get('/health', (req, res) => {
    const health = {
        status: 'healthy',
        uptime: process.uptime(),
        deliveriesLastHour: getDeliveryCount('1h'),
        successRate: getSuccessRate('1h'),
        dlqCount: getDLQCount(),
    };
    res.json(health);
});

// 2. Prometheus metrics
const metrics = {
    webhookDeliveriesTotal: new prometheus.Counter({
        name: 'webhook_deliveries_total',
        help: 'Total webhook deliveries',
        labelNames: ['status', 'provider'],
    }),
    webhookDeliveryDuration: new prometheus.Histogram({
        name: 'webhook_delivery_duration_ms',
        help: 'Webhook delivery latency',
        buckets: [100, 500, 1000, 5000, 10000],
    }),
};

// 3. Structured logging
logger.info('Webhook delivered', {
    webhookId: 'msg_123',
    subscriberId: 'sub_456',
    durationMs: 234,
    statusCode: 200,
});

// 4. Alerting on anomalies
const alertRules = [
    { metric: 'success_rate', threshold: 0.99, window: '5m' },
    { metric: 'dlq_count', threshold: 100, window: '1h' },
    { metric: 'latency_p99', threshold: 10000, window: '5m' },
];

# Webhook Documentation Template

## Event Types
| Event | Description | Payload Schema |
|-------|-------------|----------------|
| user.created | New user registered | [schema link] |
| payment.succeeded | Payment completed | [schema link] |

## Delivery
- Protocol: HTTPS POST
- Format: JSON (Standard Webhooks)
- Retry: 5 retries over 9 hours (1min, 5min, 30min, 2hr, 6hr)
- Rate limit: 100 webhooks per minute per endpoint

## Verification
- Algorithm: HMAC-SHA256
- Header: webhook-signature
- Secret: Configured in dashboard

## Best Practices for Consumers
1. Verify signatures before processing
2. Return 200 OK within 5 seconds
3. Use idempotency keys for deduplication
4. Process asynchronously
5. Log all webhook activity

## Testing
- Test mode available in dashboard
- Sample payloads for each event type
- ngrok/smee for local development