Building Scalable Webhooks with Cloudflare Workers

A developer outlined an edge-native webhook architecture built on Cloudflare Workers and Queues, in which an edge worker verifies HMAC-SHA256 signatures, enqueues payloads, and returns a 202 immediately while a separate queue consumer handles processing with retries. The pattern is demonstrated by Codra, an open-source self-hosted AI code review engine for GitHub pull requests that uses Workers and Queues to run an edge-native review loop without server maintenance.

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 https://codra.run , 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. js 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. js 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 https://codra.run . 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 https://codra.run/docs/cloudflare . 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 https://github.com/devarshishimpi/codra or reviewing its architecture overview https://codra.run/docs , 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.