Building Scalable Webhooks with Cloudflare Workers

Handling webhooks at scale presents a unique set of engineering challenges. When a third-party service (like GitHub, Stripe, or Twilio) sends an event to your application, it expects a fast, reliable, and secure response. If your server is slow, the provider might time out. If you receive a sudden spike in events, your backend could be overwhelmed.

Cloudflare Workers provide a highly effective solution for this problem. By deploying serverless functions to the edge, you can intercept, validate, and queue webhooks globally with near-zero latency. In this tutorial, we will explore the best practices for building a resilient webhook architecture and introduce Codra, an open-source AI code review engine, as a reference implementation.

When building a webhook receiver, developers must account for several critical factors:

Cloudflare Workers operate at the network edge, running within milliseconds of the user or provider making the request. They offer:

To build a scalable webhook system, follow a decoupled approach. The edge worker should only validate the request and push it to a queue.

Never trust an incoming webhook without verifying its cryptographic signature. Providers like GitHub include a signature in the headers based on a shared secret. You can compute the HMAC signature in your Worker and compare it using a constant-time comparison to prevent timing attacks.

export async function verifySignature(request, secret) {
  const signature = request.headers.get('x-hub-signature-256');
  if (!signature) return false;

  const body = await request.clone().text();
  const encoder = new TextEncoder();

  const key = await crypto.subtle.importKey(
    'raw',
    encoder.encode(secret),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign']
  );

  const signed = await crypto.subtle.sign('HMAC', key, encoder.encode(body));
  const expectedSignature = 'sha256=' + Array.from(new Uint8Array(signed))
    .map(b => b.toString(16).padStart(2, '0'))
    .join('');

  return signature === expectedSignature;
}

Do not process the webhook payload synchronously. Instead, push the payload to a message queue and return a 200 status code immediately. Cloudflare Queues are perfect for this.

export default {
  async fetch(request, env) {
    if (request.method !== 'POST') {
      return new Response('Method not allowed', { status: 405 });
    }

    const isValid = await verifySignature(request, env.WEBHOOK_SECRET);
    if (!isValid) {
      return new Response('Unauthorized', { status: 401 });
    }

    const payload = await request.json();

    // Push to Cloudflare Queue
    await env.WEBHOOK_QUEUE.send(payload);

    return new Response('Accepted', { status: 202 });
  }
};

A separate queue consumer handles the heavy lifting. This is where you can implement retries and long-running tasks without worrying about the webhook provider timing out.

export default {
  async queue(batch, env) {
    for (const message of batch.messages) {
      try {
        await processEvent(message.body);
        message.ack();
      } catch (error) {
        console.error('Processing failed', error);
        message.retry();
      }
    }
  }
};

If you are looking for a production-ready example of this architecture, check out Codra. Codra is an open-source, self-hosted AI code review engine designed specifically for GitHub pull requests. While Codra supports containerized Docker and Node.js deployments via BullMQ, its serverless deployment profile leverages Cloudflare Workers and Queues to provide an edge-native review loop with zero server maintenance (see the Cloudflare Workers deployment guide).

Codra leverages this decoupled webhook pattern to handle pull request events efficiently. When a developer pushes code, GitHub sends a webhook to the Codra ingestion worker. The worker verifies the payload and queues the review task, ensuring GitHub never experiences a timeout.

Codra focuses on providing a superior developer experience through several key features:

By examining the Codra repository or reviewing its architecture overview, developers can see how to structure large-scale Worker applications, manage secrets, and handle complex asynchronous workflows.

Building webhook infrastructure requires anticipating scale from day one. By utilizing Cloudflare Workers and Queues, developers can build a robust ingestion layer that handles traffic spikes gracefully and processes data securely. Open-source projects like Codra provide excellent blueprints for implementing these patterns in real-world scenarios.