Configure Auth Hooks

This guide covers the server-side configuration required to enable auth hooks on a self-hosted Supabase instance running with Docker Compose. Auth hooks let you run custom logic at specific points in the authentication flow - for example, adding claims to JWTs, sending SMS through a custom provider, or restricting signups.

Before you begin#

You need:

• A working self-hosted Supabase installation. See Self-Hosting with Docker.
• For Postgres function hooks: access to the database service to create functions.
• For HTTP endpoint hooks: a reachable HTTPS endpoint or a local Edge Function.

How hooks work#

For hook implementation details (input/output schemas, SQL and HTTP examples), see Auth Hooks.

Supabase Auth can call a hook at specific lifecycle events during the auth flow. Each hook can be configured with the following environment variables:

• GOTRUE_HOOK_{HOOK_NAME}_ENABLED: Enable the hook (true/false)
• GOTRUE_HOOK_{HOOK_NAME}_URI: The hook endpoint
• GOTRUE_HOOK_{HOOK_NAME}_SECRETS: Webhook signing secrets (for HTTP hooks)

URI schemes#

Hooks support two URI schemes:

Step-by-step: Postgres function hook#

This example enables the Custom Access Token hook using a Postgres function that adds a user_role claim to the JWT.

Step 1: Create the Postgres function#

You can execute the following SQL from the Supabase Dashboard SQL Editor, or by connecting to your database using a Postgres client such as psql.

This example reads roles from a user_roles table, so create that table first. If the table is missing, the hook errors and every sign-in fails.

1
create table if not exists public.user_roles (
2
  user_id uuid not null references auth.users
3
    on delete cascade,
4
  role text not null,
5
  primary key (user_id)
6
);

Then create the hook function:

1
create or replace function public.custom_access_token_hook(event jsonb)
2
returns jsonb
3
language plpgsql
4
security definer
5
set search_path = ''
6
as $$
7
declare
8
  claims jsonb;
9
  user_role text;
10
begin
11
  claims := event->'claims';
12
13
  -- Example: look up a custom role from a user_roles table
14
  select role into user_role
15
    from public.user_roles
16
    where user_id = (event->>'user_id')::uuid;
17
18
  if user_role is not null then
19
    claims := jsonb_set(
20
      claims, '{user_role}', to_jsonb(user_role)
21
    );
22
  end if;
23
24
  -- Return the modified claims
25
  return jsonb_build_object('claims', claims);
26
end;
27
$$;
28
29
-- Grant execute permission to supabase_auth_admin
30
grant execute on function public.custom_access_token_hook
31
  to supabase_auth_admin;
32
33
-- Grant schema access to supabase_auth_admin (usually already granted by default)
34
grant usage on schema public to supabase_auth_admin;
35
36
-- Revoke from public and other roles
37
revoke execute on function public.custom_access_token_hook
38
  from authenticated, anon, public;

Step 2: Update docker-compose.yml#

Update the auth service environment: block:

1
services:
2
  auth:
3
    environment:
4
      # ... existing variables ...
5
      GOTRUE_HOOK_CUSTOM_ACCESS_TOKEN_ENABLED: 'true' # 👈 enabling the hook is required
6
      GOTRUE_HOOK_CUSTOM_ACCESS_TOKEN_URI: 'pg-functions://postgres/public/custom_access_token_hook'

Step 3: Relaunch the auth service#

1
sh run.sh recreate auth

Step 4: Verify the custom claim#

Give a user a role so the hook has something to add. Replace the UUID with a real user ID from auth.users:

1
insert into public.user_roles (user_id, role)
2
values ('00000000-0000-0000-0000-000000000000', 'admin');

Sign in as that user and decode the JWT. If the hook ran successfully, the user_role claim is present. A user with no matching row in user_roles still signs in, but without the claim. If something doesn't work, check the auth logs:

1
docker compose logs auth --tail 20

Step-by-step: HTTP endpoint hook#

This example enables the Send SMS hook using an Edge Function.

Step 1: Create the Edge Function#

Create volumes/functions/send_sms/index.ts:

1
import { Webhook } from 'https://esm.sh/standardwebhooks@1.0.0'
2
3
// Note: this example assumes a single secret. If you use multiple secrets (e.g. "v1,whsec_new|v1,whsec_old"), split on '|'
4
// and try each secret in turn until wh.verify() succeeds.
5
const hookSecret = Deno.env.get('SEND_SMS_HOOK_SECRET')?.replace('v1,whsec_', '')
6
7
Deno.serve(async (req) => {
8
  if (req.method !== 'POST') {
9
    return new Response('not allowed', { status: 400 })
10
  }
11
12
  if (!hookSecret) {
13
    console.error('SEND_SMS_HOOK_SECRET environment variable not provided')
14
    return new Response('{}', { status: 500 })
15
  }
16
17
  // Verify the webhook signature
18
  const payload = await req.text()
19
  const headers = Object.fromEntries(req.headers)
20
  const wh = new Webhook(hookSecret)
21
  const { user, sms } = wh.verify(payload, headers)
22
23
  // Send SMS using your provider
24
  // ... your sms sending logic here ...
25
26
  return new Response(JSON.stringify({}), {
27
    headers: { 'Content-Type': 'application/json' },
28
  })
29
})

Step 2: Generate a webhook secret#

Generate a secret using the following command:

1
echo "v1,whsec_$(openssl rand -base64 32)"

Copy the output of this command, for example: v1,whsec_abc123....

Step 3: Update .env file#

Add the following environment variables to your .env file:

1
SEND_SMS_HOOK_URI=http://host.docker.internal:8000/functions/v1/send_sms
2
SEND_SMS_HOOK_SECRET=YOUR_GENERATED_SECRET_HERE # Paste the secret generated in the last step here

Step 4: Update docker-compose.yml#

Add the following environment variables to the auth and functions services. For brevity, only the updated fields are shown.

1
services:
2
  auth:
3
    environment:
4
      # ... existing variables ...
5
      GOTRUE_HOOK_SEND_SMS_ENABLED: 'true'
6
      GOTRUE_HOOK_SEND_SMS_URI: ${SEND_SMS_HOOK_URI}
7
      GOTRUE_HOOK_SEND_SMS_SECRETS: ${SEND_SMS_HOOK_SECRET}
8
    extra_hosts: # 👈 required so the container can resolve host.docker.internal
9
      - 'host.docker.internal:host-gateway'
10
11
  functions:
12
    environment:
13
      # ... existing variables ...
14
      SEND_SMS_HOOK_SECRET: ${SEND_SMS_HOOK_SECRET}

Step 5: Relaunch auth and functions services#

1
sh run.sh recreate auth functions

Step 6: Verify the hook fires#

Trigger an SMS authentication event and confirm that the hook executes successfully.

If something doesn't work, check the auth and functions logs:

1
docker compose logs auth --tail 20
2
docker compose logs functions --tail 20

Webhook secrets#

HTTP hooks use the Standard Webhooks specification for payload signing.

Generating a secret#

1
echo "v1,whsec_$(openssl rand -base64 32)"

Secret format#

• Symmetric: v1,whsec_[base64]{32-88 characters}

Key rotation#

Separate multiple secrets with | to rotate keys without downtime. For example:

1
SEND_EMAIL_HOOK_SECRET=v1,whsec_new-secret|v1,whsec_old-secret

1
services:
2
  auth:
3
    environment:
4
      # ... existing variables ...
5
      GOTRUE_HOOK_SEND_EMAIL_ENABLED: 'true'
6
      GOTRUE_HOOK_SEND_EMAIL_URI: 'https://example.com'
7
      GOTRUE_HOOK_SEND_EMAIL_SECRETS: ${SEND_EMAIL_HOOK_SECRET}

The Auth service signs each request with all configured secrets, so receivers can verify against either. Once all clients accept the new secret, remove the old one.

Troubleshooting#

Hook not firing#

• Check that GOTRUE_HOOK_{HOOK_NAME}_ENABLED is set to "true" (as a string) in docker-compose.yml
• Verify the variable reaches the container: sh run.sh printenv auth | grep GOTRUE_HOOK
• Remember: .env variables do not reach the container unless passed through in docker-compose.yml

pg-functions:// URI errors#

The URI format must be exactly pg-functions://postgres/<schema>/<function_name>:

• Use postgres as the host by convention. The host segment is not validated.
• Schema and function name must be valid Postgres identifiers
• The function must exist and be granted to supabase_auth_admin

HTTP hook returns errors#

Check auth logs for details:

1
docker compose logs auth --tail 20

Common causes:

• The endpoint is not reachable from the auth container
• http:// is only allowed for localhost, 127.0.0.1, ::1, and host.docker.internal

Webhook secret format mismatch#

Secrets must match the Standard Webhooks format:

• Symmetric: v1,whsec_[base64] (32-88 base64 characters after the prefix)
• No spaces or newlines in the secret string
• Generate with: echo "v1,whsec_$(openssl rand -base64 32)"

Permission denied on Postgres function#

The supabase_auth_admin role needs execute on the function. By default every role inherits execute from the public role, but the setup in Step 1 revokes it from public, so you must grant it back to supabase_auth_admin explicitly. Otherwise sign-in fails with 500: Error running hook URI, and the auth logs show a permission-denied error:

1
grant execute on function public.your_hook_function
2
  to supabase_auth_admin;

The role also needs usage on the schema. On a default install it already has this through the built-in grant on the public schema, but grant it explicitly if your database has revoked usage from public:

1
grant usage on schema public to supabase_auth_admin;

SMS OTP expiry is too short#

Refer to OTP Settings Docs