How to authenticate webhooks?

[mmkal]

I'm looking into implementing webhooks with supabase to respond to database updates. But to do this securely, we need to be able to be sure that the request is coming from Supabase, not an impersonator - and that the payload is accurate. Otherwise we have to blindly do whatever we're told by a random request that comes in.

Usually this is implemented with some kind of signature header. e.g. Stripe, Twilio - and Persona have a very simple sample implementation that doesn't require any library/SDK. It looks like it'd be possible to use pgcrypto for this.

Note: I see that there's a headers section, but pasting in a static secret value there seems not great - at the very least there should be some docs around it.

---

Answer from Supabase support to the above question:

you should also be able to flexibly sign data using pgsodium[1], which is included out of the box on projects created on our platform within the last few months.

[1] https://supabase.com/docs/guides/database/extensions/pgsodium

But if anyone has used pgsodium in this way before, or has found some other way to add authentication to webhook requests, it'd be great to see the implementation.

Or, this discussion could become a feature request - since webhooks are already providing a convenience wrapper for pg_net, maybe supabase could use pgsodium on the user's behalf and add a supabase-signature header, along with some docs on how to verify the signature (presumably something like assert.ok(await sql`select crypto_auth_verify(${signature}, ${payload}, ${key})`)

[apethree]

I have the same question, how do we validate that the request is coming from supabase itself?

[olee]

Same issue here - I would like to include the information of WHO updated some row in the webhook to ensure that RLS is respected properly.

[yaronguez]

@mmkal , did you ever find a solution? Authentication was the first question that popped in mind when I read about webhooks and I've been pretty confounded that I can't find anything. I've been thinking about including an encrypted key on the table itself that I could then verify in my edge function but I'm not sure the webhook would send the decrypted text in the payload.

[yaronguez]

A further improvement could be to adopt what HubSpot does here , pasted below:

The X-HubSpot-Signature-v3 header will be an HMAC SHA-256 hash built using the client secret of your app combined with details of the request. It will also include a X-HubSpot-Request-Timestamp header.

When validating a request using the X-HubSpot-Signature-v3 header, you'll need to 

• Reject the request if the timestamp is older than 5 minutes.
• In the request URI, decode any of the URL-encoded characters listed in the table below. You do not need to decode the question mark that denotes the beginning of the query string.

ENCODED VALUE	DECODED VALUE
%3A	:
%2F	/
%3F	?
%40	@
%21	!
%24	$
%27	'
%28	(
%29	)
%2A	*
%2C	,
%3B	;

• Create a utf-8 encoded string that concatenates together the following: requestMethod + requestUri + requestBody + timestamp. The timestamp is provided by the X-HubSpot-Request-Timestamp header.
• Create an HMAC SHA-256 hash of the resulting string using the application secret as the secret for the HMAC SHA-256 function.
• Base64 encode the result of the HMAC function.
• Compare the hash value to the signature. If they're equal then this request has been verified as originating from HubSpot. It's recommended that you use constant-time string comparison to guard against timing attacks.

[yaronguez]

The approach I will likely take:

• Define a webhook secret key in ./supbase/.env.local
• push this secret to production with supabase secrets set WEBHOOK_SECRET=XXXX
• Store a copy of this secret in my PostGres vault with select vault.create_secret('XXXX', 'WEBHOOK_SECRET', 'Description goes here');
• Create a DB trigger and function that access the secret with SELECT decrypted_secret FROM vault.decrypted_secrets WHERE name='WEBHOOK_SECRET';
• Assemble row changed payload, encrypt it, and sign it using the secret, timestamp and request details as Hubspot describes
• Send the encrypted and signed payload to the edge function with supabase_functions.http_request
• Access this secret key in my edge function with Deno.env.get(WEBHOOK_SECRET)
• Use the secret key in my edge function to decrypt and verify the signature of the payload

I'll share what I learn. It would be great if Supabase could do this automatically! Is there a place for feature requests?

[borispoehland]

Hey man, could you please help me?

This is my Postgres code:

CREATE OR REPLACE FUNCTION public.webhook()
 RETURNS trigger
 LANGUAGE plpgsql
AS $function$
DECLARE
  decrypted_secret_key text;
  headers jsonb;
BEGIN
  SELECT decrypted_secret INTO decrypted_secret_key
  FROM vault.decrypted_secrets
  WHERE name='Webhook';

  headers := jsonb_build_object('Secret-Key', decrypted_secret_key);
  
  PERFORM supabase_functions.http_request(
    'https://website.com/api/supabase', 
    'POST', 
    headers::text, 
    jsonb_build_object(
      'old_record', OLD,
      'record', NEW,
      'type', TG_OP,
      'table', TG_TABLE_NAME,
      'schema', TG_TABLE_SCHEMA
    )::text, 
    '1000'
  );

  RETURN NEW;
END;
$function$
;

CREATE TRIGGER listing_delete AFTER DELETE ON public."PropertyListings" FOR EACH ROW EXECUTE FUNCTION webhook();

CREATE TRIGGER listing_insert AFTER INSERT ON public."PropertyListings" FOR EACH ROW EXECUTE FUNCTION webhook();

CREATE TRIGGER listing_update AFTER UPDATE ON public."PropertyListings" FOR EACH ROW EXECUTE FUNCTION webhook();

So is this enough to compare the secret key of the headers with the one in my environment variables on https://website.com/api/supabase?

[yaronguez]

Hi @borispoehland , sorry I didn't see your message sooner. I ended up not using webhooks at all for my solution so I didn't follow through on my idea. However, looking through your code, I don't think it's secure enough. Take a look at the approach I described above, specifically:

• Concatenate the requestBody + timestamp.
• Create an HMAC SHA-256 hash of the resulting string using the secret key for the HMAC SHA-256 function.
• Base64 encode the result of the HMAC function.
• Insert the above into the header as 'Webhook-Signature'
• Insert the timestamp into the header as 'Webhook-TImestamp'
• In the edge function, reject the request if the timestamp is older than 5 minutes.
• Assemble the signature in the edge function in the same way as above and compare the two. If they're equal then this request has been verified.

[skorfmann]

for the record there's an issue for this already #2691

[foxted]

I ran into that issue myself, so I created a little video to explain how I solved this: https://www.youtube.com/watch?v=iyTfdYVIQiE.

You can find the associated article here as well: https://valentinprugnaud.dev/articles/setup-webhook-signature-with-supabase

[therealpurplemana]

Thank you for the implementation but this should really be a one click / flag feature for the supabase -> supabase calls!

[therealpurplemana]

@foxted is there an error in this line in your example:

-- Generate the signature
signature = generate_hmac(secret, 'message');

Shouldn't the payload be encrypted with the secret instead of a static message?

[therealpurplemana]

Does anyone know how to decode this using Deno? Here's a generic postgres function that uses @foxted method below. I tried a few different methods with hmac but couldn't get the signatures to match.

CREATE OR REPLACE FUNCTION public.signed_webhook(webhook_url TEXT, payload JSONB)
RETURNS VOID 
SECURITY DEFINER
AS $$
DECLARE
  secret_key TEXT;
  headers_json JSONB;
  payload_text TEXT;
  signature TEXT;
BEGIN
  -- Read secret key from decrypted vault data based on the new query
  SELECT decrypted_secret INTO secret_key FROM vault.decrypted_secrets WHERE name = 'webhook_secret_key' LIMIT 1;
  
  -- Convert payload to TEXT
  payload_text := payload::TEXT;
  
  -- Generate signature using the secret and payload text
  signature := generate_hmac(secret_key, payload_text);
  
  -- Construct the headers as JSONB object
  headers_json := jsonb_build_object('X-Supabase-Signature', signature, 'Content-Type', 'application/json');
  
  -- Call the net.http_post function with the required parameters including payload in the body
  PERFORM net.http_post(
    url := webhook_url,
    body := payload,
    headers := headers_json
  );
END;
$$ LANGUAGE plpgsql;

[foxted]

Not too familiar with Deno (that's why I went with a Nest.js API instead), but a quick Chat-GPT conversation gives me something like this:

import { createHmac } from "https://deno.land/std/hash/mod.ts";

const supabaseWebhookConfig = {
  webhookConfig: {
    headerName: "x-supabase-signature",
    secret: "your-secret-key",
  },
};

async function validateSupabaseWebhook(req) {
  if (!supabaseWebhookConfig.webhookConfig) {
    console.warn(
      "Supabase Webhook Guard is not configured. Please check your SupabaseModule configuration."
    );
    return false;
  }

  const headerName = supabaseWebhookConfig.webhookConfig.headerName ||
    "x-supabase-signature";
  const signature = req.headers.get(headerName);
  const body = await req.json();

  if (!signature) {
    console.warn(
      "Supabase Webhook Guard: Signature not found in the request headers."
    );
    return false;
  }

  const decodedSignature = new TextDecoder("base64").decode(
    new Uint8Array(new TextEncoder().encode(signature))
  );
  const calculatedSignature = createHmac("sha256",
    supabaseWebhookConfig.webhookConfig.secret).update(JSON.stringify(body))
    .digest("base64");

  const hmacMatch = (decodedSignature === calculatedSignature);

  if (!hmacMatch) {
    console.warn(
      "Supabase Webhook Guard: Request could not be authenticated."
    );
    return false;
  } else {
    console.log("Supabase Webhook Guard: Request authenticated.");
  }

  return true;
}

Deno.serve(async (req) => {
  if (!(await validateSupabaseWebhook(req))) {
    return new Response("Unauthorized", { status: 401 });
  }

  const { name } = await req.json();
  const data = {
    message: `Hello ${name}!`,
  };

  return new Response(JSON.stringify(data), {
    headers: { 'Content-Type': 'application/json' },
  });
});

console.log("Server running on http://localhost:8000/");

For reference, this is the module I built for Nest.js to handle this automagically for me: https://github.com/SetlistPro/nestjs-supabase-webhooks

[jibin2706]

this is exactly what I needed

[jibin2706]

thanks @foxted

[arjunacharya10]

I have a question - noob here so I might be way off and i Dont know anything about deno: In the supabase webhook UI: https://supabase.com/dashboard/project/_/database/hooks , cant we just set a custom header with a value which we can compare on the server side ?

Im asking coz, In the above method we are not encrypting a payload, we are generating a standard string for every message and it is not dependant on the payload. So wouldn't just adding a custom header help me verify if the message is from supabase?

[bitnom]

Hi! I was wondering what about this instead

That looks like the easiest option but how the hell is it safe to do that in a public schema? It ends up as as a trigger on the table:

create trigger my_webhook
after insert on my_table for each row
execute function supabase_functions.http_request (
  'https://xxx.supabase.co/functions/v1/my-edge-func',
  'POST',
  '{"Content-type":"application/json","Authorization":"Bearer eyJhbxxxxxxxxxxx"}',
  '{}',
  '5000'
);

Do users have no way of inspecting the schema authenticated with the anon key?

[encima]

Functions is a protected schema and you can also be excluded from dumps in the CLI

[ChuckJonas]

@encima not having part of your code in source control breaks the reproducible and deployable builds "tenant" and is not acceptable for some of us who have strict DevOps standards.

You could instead store the key as a secret in the vault.

[encima]

This is true, but not having sensitive data in your repos is also key to that. As you say, this could be stored in the vault or using tools like gitpass. I agree that the complexity added does make this harder but the key itself does not need to be stored in the trigger, it just needs to be retrievable by the trigger

[ChuckJonas]

Here's an example of a Postgres Function that uses vault to authenticate with a Deno Function:

DECLARE
  idle_chats_count INTEGER;
BEGIN
  SELECT count(id) INTO idle_chats_count FROM get_idle_chats(2);
  IF idle_chats_count > 0 THEN
    PERFORM
      net.http_post(
          url:=concat((
                  SELECT decrypted_secret 
                  FROM vault.decrypted_secrets 
                  WHERE name = 'api_url' 
                  LIMIT 1)
                ,'/functions/v1/idleChat'),
          headers:=json_build_object(
            'Content-Type', 'application/json', 
            'Authorization', concat('Bearer ', (
              SELECT decrypted_secret 
              FROM vault.decrypted_secrets 
              WHERE name = 'service_key' 
              LIMIT 1))
            )::jsonb,
          body:=concat('{"time": "', now(), '"}')::jsonb
      );
  END IF;
  RETURN idle_chats_count;
END 

You must manually set the vault secrets yourselve (it would be nice if they were part of the supabase env instead)

[gc-ft]

This is true, but not having sensitive data in your repos is also key to that. As you say, this could be stored in the vault or using tools like gitpass. I agree that the complexity added does make this harder but the key itself does not need to be stored in the trigger, it just needs to be retrievable by the trigger

@encima usually edge functions require a valid JWT to work (unless specifically disabled). The Supabase Dashboard when setting up Webhooks offers an option to add the Authorization header for these cases. This will create a trigger which uses the service role key in clear text. You yourself acknowledge this is not great and not required because the key could be retrieved by the trigger function?

This is also a big devops problem if done this way because updating in various setups (staging and production for example) would require manual intervention to change these keys in the triggers?

Why not change the behaviour of the dashboard to something similar to what @ChuckJonas wrote, but using an internal supabase function that retrieve the service role key? I understand we can do this manually by duplicating the service role key into the vault, but why so complicated if it can be done internally by supabase much more efficiently?

[encima]

Hey all,

Thanks for the candid feedback and constructive approaches. The feedback has been passed on to the team for @supabase/edge-functions and they are looking at ways to address this!

[njoshi22]

Hey - is there an update on this?

[gc-ft]

I have been thinking about this the last few days, and one extra possible solution, and possibly nicer than using the service_role key, would be to setup the webhook with the same auth header as the current postgREST session has, if the trigger was executed due to a postgREST call.

The trigger should be happening in the same transaction/session as the postgREST call, which would mean that current_setting('request.headers') will be set to a json of all headers. So the code below will retrieve the current Authorization header into the variable current_auth:

headers := current_setting('request.headers', true)::jsonb;

SELECT elem->>'Authorization' INTO current_auth
FROM jsonb_array_elements(headers) AS elem
WHERE elem ? 'Authorization';

So basically the webhook would be called somewhat like 'security invoker' rules inside postgres would call a function, with the JWT of the request triggering the original query that triggered the webhook to run.

I must admit, I did not test this, but as long as the trigger originated from a PostgREST initiated session, I do not see why this would not be the case?

I will do some tests and report back if someone is interested. I am also working on a nicer way to "handle" webhooks in general on our implementations, will share this in the coming days once finished with the community.

[elyobo]

I'm trying this approach, which I've copied from my comment on https://github.com/orgs/supabase/discussions/12813#discussioncomment-10624304; it implements signatures like the custom auth hooks.

--

Thanks, this was a great start. I saw that the custom auth hook uses the webhook standard which makes the verification code in the hook very simple and also protects against message modification (content is signed) and replay (to some extent) via timestamps.

Using pgsodium (🚨 which supabase notes is pending deprecation but I don't know the replacement) we can send a compliant request with something like the following.

First we can get a shared secret using pgsodium (which is extremely fussy about the key length here...).

select encode(pgsodium.crypto_auth_hmacsha256_keygen(), 'base64');

Then we can store that secret value in vault, along with the project URL (I've put these both in my seed, and populated them separately in production, so that I can use this in local dev).

select vault.create_secret(
  -- not my secret for anything, just generated for example
  'qHUp608CcaSPRRZVUNbf6cke3M2PgRZkrCWg3UPeNMY=',
  'my_function_secret',
  'shared secret for my-function'
);

select vault.create_secret(
  'http://host.docker.internal:54321',
  'project_url',
  'supabase project url'
);

Then we can create a trigger like this to e.g. push through inserts.

create or replace function public.call_edge_function_from_trigger()
returns trigger
set search_path = ''
as $$
declare
  function_name text;
  secret_name text;
  project_url text;
  full_url text;
  webhook_timestamp text;
  webhook_payload jsonb;
begin
  function_name := tg_argv[0];
  secret_name := tg_argv[1];

  select floor(extract(epoch from now()))::bigint::text into webhook_timestamp;
  project_url := private.get_secret('project_url');
  full_url := project_url || '/functions/v1/' || function_name;
  webhook_payload := jsonb_build_object(
    'type', tg_op,
    'table', tg_table_name,
    'schema', tg_table_schema,
    'record', new,
    'old_record', old
  );

  -- call the http_request function with the constructed url
  perform net.http_post(
    url := full_url,
    headers := jsonb_build_object(
      'content-type', 'application/json',
      'webhook-id', function_name,
      'webhook-timestamp', webhook_timestamp,
      'webhook-signature', 'v1,' || encode(
        pgsodium.crypto_auth_hmacsha256(
          (function_name || '.' || webhook_timestamp || '.' || webhook_payload::text)::bytea,
          decode(private.get_secret(secret_name), 'base64')
        ),
        'base64'
      )
    ),
    body := webhook_payload,
    timeout_milliseconds := 5000
  );

  return null;
end;
$$ language plpgsql;

drop trigger if exists send_board_match_notifications on public.board;
create trigger send_board_match_notifications
after insert on public.mytable
for each row
execute function public.call_edge_function_from_trigger(
  'my-function',
  'my_function_secret'
);

And on the Deno edge function side (presumably also usable in some form elsewhere too) we have something like this to verify it, assuming that the same base4 encoded secret has been saved in a function secret MY_FUNCTION_SECRET_SECRET. It would indeed be great if the edge function secrets were accessible in the PG vault without having to duplicate it, but one day maybe.

import { Webhook } from 'https://esm.sh/[email protected]'
import { createClient } from '@supabase/supabase-js'

import "jsr:@supabase/functions-js/edge-runtime.d.ts"
import { ok, serverError } from '../_shared/responses.ts'

console.log("Hello from Functions!")

Deno.serve(async (req) => {
    const payload = await req.text()
    const base64_secret = Deno.env.get('MY_FUNCTION_SECRET_SECRET') ?? ''
    const headers = Object.fromEntries(req.headers)
    console.log(headers)
    const wh = new Webhook(base64_secret)
    try {
      const verified = wh.verify(payload, headers)
      console.log(verified)
      const supabase = createClient(
        Deno.env.get('SUPABASE_URL') ?? '',
        Deno.env.get('SUPABASE_SERVICE_ROLE_KEY') ?? '',
      )
      return ok({ message: 'ok' })
    } catch (error) {
      console.error('Unhandled error', error)
      return serverError({
        error: `Failed to process the request: ${error}`,
      })
    }
})

Implementation details taken from the JS standardwebhooks implementation.

[elyobo]

This doesn't tell you the current user, but it could be added (and, because of the signature, could presumably be trusted as well).

[rahul2008d]

I have integrated Supabase with Clerk and set up webhooks for user events like user.created and user.updated. While other CRUD operations are functioning correctly with the Clerk token, I am encountering an issue during webhook events where the Clerk token is not being sent.

For existing users, everything works perfectly, and the token is received. However, during the webhook events, I receive the following error from Supabase:

{
code: 'PGRST301',
details: null,
hint: null,
message: 'JWSError (CompactDecodeError Invalid number of parts: Expected 3 parts; got 1)'
}

This error seems to be related to the missing Clerk token during the webhook flow, despite the route being set up correctly. The issue only arises with webhook events, not with other operations.

Here is the relevant code snippet for creating the Supabase client:

route.js for webhook event capturing

export function createClerkSupabaseClientSsr() {
  const { getToken } = auth();

  return createClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL,
    process.env.NEXT_PUBLIC_SUPABASE_KEY,
    {
      global: {
        fetch: async (url, options = {}) => {
          const clerkToken = await getToken({ template: "supabase" });
          const headers = new Headers(options?.headers);
          headers.set("Authorization", `Bearer ${clerkToken}`);
          return fetch(url, { ...options, headers });
        },
      },
    }
  );
}

In the webhook setup, I correctly verify the event and headers, but the missing Clerk token is causing the JWT error. Could you help investigate why the token is not being sent during webhook events and how to resolve this?

Here's the complete code for better context:

// route.js for webhook handling
import { Webhook } from "svix";
import { headers } from "next/headers";
import { createSupabaseUser } from "@/app/_lib/actions";
import { NextResponse } from "next/server";
import { auth } from "@clerk/nextjs/server";

export async function POST(req) {
  const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;
  if (!WEBHOOK_SECRET) throw new Error("Please add WEBHOOK_SECRET to .env or .env.local");

  const headerPayload = headers();
  const svix_id = headerPayload.get("svix-id");
  const svix_timestamp = headerPayload.get("svix-timestamp");
  const svix_signature = headerPayload.get("svix-signature");

  if (!svix_id || !svix_timestamp || !svix_signature) {
    return new Response("Error occured -- no svix headers", { status: 400 });
  }

  const payload = await req.json();
  const body = JSON.stringify(payload);
  const wh = new Webhook(WEBHOOK_SECRET);
  let evt;
  try {
    evt = wh.verify(body, { "svix-id": svix_id, "svix-timestamp": svix_timestamp, "svix-signature": svix_signature });
  } catch (err) {
    console.error("Error verifying webhook:", err);
    return new Response("Error occured", { status: 400 });
  }

  const { id, eventType } = evt.data;
  if (eventType === "user.created") {
    const { getToken } = auth();
    const { token } = await getToken({ template: "supabase" });
    console.log(token);

    const { fullName, email_addresses, image_url, username } = evt.data;
    const email = email_addresses[0].email_address;
    try {
      const { data: userData } = await createSupabaseUser({ id, fullName, email, image_url, username });
      return NextResponse.json({ message: "User created successfully", id: userData?.id }, { status: 200 });
    } catch (error) {
      console.log(error);
      throw new Response("Failed to create the user!", { status: 500 });
    }
  }
}

server action :

'use server'
export async function createSupabaseUser(user) {
  try {
    const { id, fullName, email, image_url, username } = user;
    const newUser = { user_id: id, fullName, email, imageUrl: image_url, isUCMember: false };
    const supabaseClient = createClerkSupabaseClientSsr();
    const { data, error } = await supabaseClient.from("User").insert(newUser).select();
    console.log("insertion error: ", error);
    return data;
  } catch (error) {
    console.log(error);
    throw new Error("User could not be created");
  }
}

Please can anyone help ?

[SadmanYasar]

I faced this issue yesterday as I was trying to create vector embeddings after a table row is updated or created and had a webhook that called an edge function. Based on this tutorial, I added the anon key as Authorization header when setting up the webhook with "Bearer " as the initial in the value of the header. Then it worked fine. I think the docs should be a bit more clearer and updated as I couldn't figure out what the jwt value is until I watched the video, which is the anon key itself.

[alexrabin]

I don't recommend doing this. If someone gets access to your anon key through inspecting your website using Supabase then they now can call that url with your anon key