How to Receive and Replay External Webhooks in Supabase Edge Functions with Hookdeck

Webhooks have revolutionized the way applications communicate and share data in real-time. When it comes to extending the capabilities of Supabase Edge Functions by efficiently handling and replaying webhooks, Hookdeck is an invaluable tool.

Hookdeck is a webhook management platform that helps developers reliably receive webhooks, manage events and troubleshoot any issues quickly. By integrating Hookdeck with Supabase Edge Functions, you can enhance the reliability and management of your webhook events, ensuring seamless integration with external systems.

This article delves into the process of receiving and replaying external webhooks in Supabase Edge Functions using Hookdeck.

Create a Supabase Edge Function

Before we explore webhook replay, let's set up a Supabase Edge Function to receive incoming webhook events. Supabase Edge Functions are serverless TypeScript functions that run on Deno at the edge, distributed globally across Supabase's network. They're a natural fit for webhook endpoints thanks to fast cold starts and built-in support for the Web Crypto API for signature verification.

This example assumes you have the Supabase CLI installed and are familiar with creating and deploying Supabase Edge Functions.

To create a Supabase Edge Function:

• Ensure you have the Supabase CLI installed and authenticated for a project as described here.

• Open up your terminal and navigate to your Supabase project.

• Create a new Edge Function called webhook-handler using the following command:

  supabase functions new webhook-handler
  

This command generates a function stub in the supabase/functions/webhook-handler/index.ts file.

• Replace the content of the file with the following example code snippet to receive and process webhook payloads.

  Deno.serve(async (req) => {
    if (req.method !== "POST") {
      return new Response(JSON.stringify({ error: "Method Not Allowed" }), {
        status: 405,
        headers: { "Content-Type": "application/json" },
      });
    }
  
    // Read the raw body as text first (important if you need to verify signatures)
    const body = await req.text();
    const payload = JSON.parse(body);
  
    // Respond immediately, then process in the background
    EdgeRuntime.waitUntil(processWebhook(payload));
  
    return new Response(
      JSON.stringify({ message: "Webhook received successfully!" }),
      { status: 200, headers: { "Content-Type": "application/json" } },
    );
  });
  
  async function processWebhook(payload: unknown) {
    // Perform any heavy processing here (database writes, API calls, etc.)
    // This runs for up to 150s (free) or 400s (paid) after the response is sent
    console.log("Webhook received:", payload);
  }
  

• Since external webhook providers can’t send Supabase JWTs, you need to disable JWT verification for this function. Add the following to your supabase/config.toml:

  [functions.webhook-handler]
  verify_jwt = false
  

With JWT verification disabled, the endpoint is publicly accessible. If your webhook source supports signature verification (e.g., Stripe’s Stripe-Signature or GitHub’s X-Hub-Signature-256), implement HMAC validation in your function to verify requests are authentic. Store your signing secret using supabase secrets set WEBHOOK_SECRET=your-secret.

• Deploy the newly created function to production using:

  supabase functions deploy webhook-handler --no-verify-jwt
  

  You get prompted to input the project ref. This can be seen in the URL bar when you visit your Supabase project’s dashboard, https://supabase.com/dashboard/project/<project-ref>.

This bundles the function and deploys it to the Supabase platform.

• Back on your Supabase project dashboard, switch to the Edge Functions sidebar, and open the webhook-handler function you just deployed. On the Details tab, you should see the Endpoint URL; copy that as it is needed below. The URL follows the format: https://YOUR_PROJECT_ID.supabase.co/functions/v1/webhook-handler

Execution limits: Edge Functions have a 2-second CPU time limit per request (time spent waiting on network I/O like database queries or API calls does not count). The total wall clock duration is 150 seconds on the free plan and 400 seconds on paid plans. Memory is limited to 256MB per invocation. The code above uses EdgeRuntime.waitUntil() to respond immediately while continuing to process the webhook payload in the background within these time limits.

Replay webhooks

Using Hookdeck as a bridge between your source platform's webhooks and Supabase Edge Functions, you can replay any failed events that weren't processed correctly.

Follow the steps below to implement webhook replay using Hookdeck.

Create a Hookdeck connection

1. Sign up or log in to your Hookdeck dashboard.
2. Click on Connections in the side panel, then click +Create Connection to set up a new connection.
3. Fill in the required information:
   • Source: Specify the source platform or application that will send webhooks
   • Destination: Enter the URL of your Supabase Edge Function
4. Save the connection.

Hookdeck provides you with a URL that you can use on the source platform to send webhook events.

Receive webhook events

You can use Hookdeck Console to simulate example webhooks from popular webhook sources.

Imagine your webhook source is Stripe. When an event is triggered, you can monitor it on both the Hookdeck dashboard and in your Supabase Edge Function logs.

From your Hookdeck dashboard, go to the Events tab in the side panel. Filter events based on the connection you created earlier. This shows the event activities on that connection.

In your Supabase Edge Function logs, you can observe incoming events and their processing status.

Replaying error or failed webhooks

One of the valuable features provided by Hookdeck is the ability to replay webhooks. This feature becomes especially useful when a webhook event fails to process correctly in your Supabase Edge Function.

To replay a failed webhook event:

1. From the Hookdeck Event panel, locate the failed event. Click on the kebab menu (three vertical dots) across from it.
2. Select Retry from the menu. This action resends the event to your Supabase Edge Function, giving it another chance to process the event successfully.

Now you know how to receive and replay webhook events for your Supabase Edge Functions using Hookdeck. By harnessing Hookdeck's powerful capabilities including security, routing, and analytics, you can effectively manage and troubleshoot webhook events from various external platforms.

The integration of Hookdeck with Supabase Edge Functions empowers you to build dynamic and reliable event-driven architectures. This ensures seamless communication and real-time data transfer between your Supabase projects and external systems. Dive deeper into Hookdeck's documentation to explore further features and possibilities.