Webhooks
Receiving Webhooks
Express (with signature verification)
app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['stripe-signature']!;
const event = stripe.webhooks.constructEvent(req.body, signature, WEBHOOK_SECRET);
// Idempotency: check if already processed
const existing = await db.webhookEvent.findUnique({ where: { eventId: event.id } });
if (existing) return res.json({ received: true });
// Process
switch (event.type) {
case 'checkout.session.completed':
await fulfillOrder(event.data.object);
break;
}
// Mark as processed
await db.webhookEvent.create({ data: { eventId: event.id, type: event.type } });
res.json({ received: true });
});
Generic HMAC Verification
import { createHmac, timingSafeEqual } from 'crypto';
function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean {
const expected = createHmac('sha256', secret).update(payload).digest('hex');
return timingSafeEqual(Buffer.from(signature), Buffer.from(`sha256=${expected}`));
}
app.post('/webhooks/github', express.raw({ type: '*/*' }), (req, res) => {
const sig = req.headers['x-hub-signature-256'] as string;
if (!verifyWebhookSignature(req.body.toString(), sig, GITHUB_SECRET)) {
return res.status(401).json({ error: 'Invalid signature' });
}
// Process event...
res.status(200).json({ received: true });
});
Sending Webhooks
class WebhookDispatcher {
async dispatch(url: string, event: WebhookEvent, secret: string) {
const payload = JSON.stringify(event);
const signature = createHmac('sha256', secret).update(payload).digest('hex');
const response = await fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Webhook-Signature': `sha256=${signature}`,
'X-Webhook-Id': event.id,
'X-Webhook-Timestamp': new Date().toISOString(),
},
body: payload,
signal: AbortSignal.timeout(10000),
});
if (!response.ok) throw new WebhookDeliveryError(response.status);
}
}
Retry with Exponential Backoff
// Use job queue for reliable delivery
await webhookQueue.add('deliver', {
url: subscription.url,
event: { id: uuid(), type: 'order.created', data: order },
secret: subscription.secret,
}, {
attempts: 5,
backoff: { type: 'exponential', delay: 60000 }, // 1m, 2m, 4m, 8m, 16m
});
Webhook Event Schema
interface WebhookEvent {
id: string; // Unique event ID (for idempotency)
type: string; // 'order.created', 'user.deleted'
timestamp: string; // ISO 8601
data: unknown; // Event payload
version: string; // API version
}
Anti-Patterns
| Anti-Pattern | Fix |
|---|
| No signature verification | Always verify HMAC signature |
| Processing before responding 200 | Respond 200 immediately, process async |
| No idempotency check | Store processed event IDs |
| Using parsed body for verification | Use raw body for signature check |
| No retry on send failures | Use job queue with exponential backoff |
| Synchronous webhook delivery | Dispatch via background job queue |
Production Checklist
- HMAC signature verification on receive
- Raw body parsing (not JSON-parsed) for signature
- Idempotency: deduplicate by event ID
- Respond 200 before processing
- Retry with exponential backoff on send
- Dead letter queue for failed deliveries
- Webhook event log for debugging
