Webhooks Implementation Guide

Webhooks enable real-time communication between services. When events happen, you notify interested parties immediately instead of waiting for them to poll. Here's how to build reliable webhook systems.

Receiving Webhooks#

Basic Endpoint#

import crypto from 'crypto';

// Verify webhook signature
function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expected}`)
  );
}

// Webhook endpoint
app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), async (req, res) => {
  const signature = req.headers['stripe-signature'] as string;
  const payload = req.body.toString();

  // Verify signature
  if (!verifyWebhookSignature(payload, signature, STRIPE_WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(payload);

  // Acknowledge immediately
  res.status(200).json({ received: true });

  // Process asynchronously
  await processWebhookEvent(event);
});

async function processWebhookEvent(event: StripeEvent) {
  // Idempotency check
  const processed = await redis.get(`webhook:${event.id}`);
  if (processed) {
    logger.info('Webhook already processed', { eventId: event.id });
    return;
  }

  try {
    switch (event.type) {
      case 'payment_intent.succeeded':
        await handlePaymentSuccess(event.data.object);
        break;
      case 'customer.subscription.deleted':
        await handleSubscriptionCanceled(event.data.object);
        break;
      default:
        logger.info('Unhandled webhook event', { type: event.type });
    }

    // Mark as processed
    await redis.set(`webhook:${event.id}`, '1', 'EX', 86400 * 7);
  } catch (error) {
    logger.error('Webhook processing failed', {
      eventId: event.id,
      error: error.message,
    });
    throw error;
  }
}

Queue-Based Processing#

// Better: Queue webhooks for processing
app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), async (req, res) => {
  const signature = req.headers['stripe-signature'] as string;

  if (!verifySignature(req.body, signature)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(req.body.toString());

  // Store and acknowledge
  await prisma.webhookEvent.create({
    data: {
      eventId: event.id,
      type: event.type,
      payload: event,
      status: 'pending',
    },
  });

  // Queue for processing
  await queue.add('process-webhook', { eventId: event.id });

  res.status(200).json({ received: true });
});

// Worker processes webhooks
queue.process('process-webhook', async (job) => {
  const { eventId } = job.data;

  const webhook = await prisma.webhookEvent.findUnique({
    where: { eventId },
  });

  if (!webhook || webhook.status === 'processed') {
    return;
  }

  try {
    await processWebhookEvent(webhook.payload);

    await prisma.webhookEvent.update({
      where: { eventId },
      data: { status: 'processed', processedAt: new Date() },
    });
  } catch (error) {
    await prisma.webhookEvent.update({
      where: { eventId },
      data: {
        status: 'failed',
        error: error.message,
        attempts: { increment: 1 },
      },
    });

    throw error; // Retry
  }
});

Sending Webhooks#

Webhook Delivery Service#

interface WebhookSubscription {
  id: string;
  url: string;
  secret: string;
  events: string[];
  active: boolean;
}

class WebhookService {
  async send(
    subscription: WebhookSubscription,
    event: string,
    payload: object
  ): Promise<WebhookDelivery> {
    const delivery = await prisma.webhookDelivery.create({
      data: {
        subscriptionId: subscription.id,
        event,
        payload,
        status: 'pending',
      },
    });

    try {
      const body = JSON.stringify({
        id: delivery.id,
        event,
        timestamp: new Date().toISOString(),
        data: payload,
      });

      const signature = this.sign(body, subscription.secret);

      const response = await fetch(subscription.url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-Webhook-Signature': signature,
          'X-Webhook-Event': event,
          'X-Webhook-Delivery': delivery.id,
        },
        body,
        signal: AbortSignal.timeout(30000),
      });

      await prisma.webhookDelivery.update({
        where: { id: delivery.id },
        data: {
          status: response.ok ? 'delivered' : 'failed',
          statusCode: response.status,
          response: await response.text().catch(() => null),
          deliveredAt: new Date(),
        },
      });

      return delivery;
    } catch (error) {
      await prisma.webhookDelivery.update({
        where: { id: delivery.id },
        data: {
          status: 'failed',
          error: error.message,
          attempts: { increment: 1 },
        },
      });

      throw error;
    }
  }

  private sign(payload: string, secret: string): string {
    const timestamp = Math.floor(Date.now() / 1000);
    const signature = crypto
      .createHmac('sha256', secret)
      .update(`${timestamp}.${payload}`)
      .digest('hex');

    return `t=${timestamp},v1=${signature}`;
  }
}

Retry with Exponential Backoff#

class WebhookRetryService {
  private readonly maxRetries = 5;
  private readonly baseDelay = 60; // seconds

  async scheduleRetry(deliveryId: string, attempt: number): Promise<void> {
    if (attempt >= this.maxRetries) {
      await this.markAsFailed(deliveryId);
      return;
    }

    // Exponential backoff: 1m, 5m, 25m, 2h, 10h
    const delay = this.baseDelay * Math.pow(5, attempt);

    await queue.add(
      'retry-webhook',
      { deliveryId, attempt: attempt + 1 },
      { delay: delay * 1000 }
    );
  }

  async retry(deliveryId: string, attempt: number): Promise<void> {
    const delivery = await prisma.webhookDelivery.findUnique({
      where: { id: deliveryId },
      include: { subscription: true },
    });

    if (!delivery || delivery.status === 'delivered') {
      return;
    }

    try {
      await webhookService.send(
        delivery.subscription,
        delivery.event,
        delivery.payload
      );
    } catch (error) {
      await this.scheduleRetry(deliveryId, attempt);
    }
  }

  private async markAsFailed(deliveryId: string): Promise<void> {
    await prisma.webhookDelivery.update({
      where: { id: deliveryId },
      data: { status: 'permanently_failed' },
    });

    // Notify subscription owner
    await notificationService.send({
      type: 'webhook_failure',
      deliveryId,
    });
  }
}

Event Fan-Out#

// Dispatch events to all subscribers
async function dispatchEvent(
  event: string,
  payload: object
): Promise<void> {
  const subscriptions = await prisma.webhookSubscription.findMany({
    where: {
      active: true,
      events: { has: event },
    },
  });

  const deliveries = subscriptions.map((sub) =>
    queue.add('send-webhook', {
      subscriptionId: sub.id,
      event,
      payload,
    })
  );

  await Promise.all(deliveries);

  logger.info('Webhook event dispatched', {
    event,
    subscriberCount: subscriptions.length,
  });
}

// Usage
await dispatchEvent('order.created', {
  orderId: order.id,
  customerId: order.customerId,
  total: order.total,
});

Subscription Management#

// API for managing webhook subscriptions
app.post('/api/webhooks', authenticate, async (req, res) => {
  const { url, events } = req.body;

  // Validate URL
  if (!isValidUrl(url)) {
    return res.status(400).json({ error: 'Invalid URL' });
  }

  // Generate secret
  const secret = crypto.randomBytes(32).toString('hex');

  const subscription = await prisma.webhookSubscription.create({
    data: {
      userId: req.user.id,
      url,
      events,
      secret,
      active: true,
    },
  });

  // Return secret only on creation
  res.json({
    id: subscription.id,
    url: subscription.url,
    events: subscription.events,
    secret, // Only shown once!
  });
});

// Test endpoint
app.post('/api/webhooks/:id/test', authenticate, async (req, res) => {
  const subscription = await prisma.webhookSubscription.findFirst({
    where: {
      id: req.params.id,
      userId: req.user.id,
    },
  });

  if (!subscription) {
    return res.status(404).json({ error: 'Not found' });
  }

  const delivery = await webhookService.send(
    subscription,
    'webhook.test',
    { message: 'This is a test webhook' }
  );

  res.json({
    success: delivery.status === 'delivered',
    statusCode: delivery.statusCode,
  });
});

Best Practices#

Receiving:
✓ Always verify signatures
✓ Respond quickly (200 OK)
✓ Process asynchronously
✓ Implement idempotency
✓ Handle duplicates gracefully

Sending:
✓ Sign all webhooks
✓ Include event type in headers
✓ Retry with exponential backoff
✓ Set reasonable timeouts
✓ Provide delivery logs
✓ Allow re-sending failed webhooks

Conclusion#

Webhooks enable real-time integrations without polling. Verify signatures for security, process asynchronously for reliability, and implement retries for resilience.

Both sending and receiving require careful handling of failures—plan for them from the start.

Share this article