Send a welcome email from Supabase

Supabase fires a Database Webhook when a row changes. Mirror new signups into a table and one becomes a welcome email.

What you will build

Prerequisites

A Supabase project, and somewhere to host an HTTPS route
A published to send

Secure it with a shared secret

Supabase Database Webhooks are built on pg_net, and they do not sign the payload. Clerk uses Svix and Stripe signs the raw bytes, so both let you prove a request came from them. Supabase gives you custom HTTP headers instead. That means the check is yours to add, and it is not optional. Your route will sit on a public URL, and without a secret anyone who finds it can post a fake signup. Generate a long random value, add it as a header on the webhook, and compare it in the handler with a constant-time comparison.

Set it up

Mirror new signups into a public table

Point the webhook at a table in public, not at auth.users directly.The auth schema belongs to the supabase_auth_admin role, which holds only the permissions it needs for authentication. A trigger firing there and reaching outside the schema hits permission denied for schema auth. Most Supabase apps already keep a profiles table for exactly this reason.

create table public.profiles (
  id uuid primary key references auth.users on delete cascade,
  email text,
  full_name text
);

-- security definer runs as the function's owner, so it may write to public.
create function public.handle_new_user()
returns trigger
language plpgsql
security definer set search_path = ''
as $$
begin
  insert into public.profiles (id, email, full_name)
  values (new.id, new.email, new.raw_user_meta_data ->> 'full_name');
  return new;
end;
$$;

create trigger on_auth_user_created
  after insert on auth.users
  for each row execute function public.handle_new_user();

security definer is the load-bearing line. Without it the trigger runs as supabase_auth_admin and cannot write to public.

Create the webhook

In the Supabase Dashboard, go to Database → Webhooks and create one:

Table: public.profiles
Events: Insert
Type: HTTP Request, POST, pointing at your route
HTTP Headers: add x-webhook-secret with your random value

Supabase sends this payload, whatever the table:

{
  "type": "INSERT",
  "table": "profiles",
  "schema": "public",
  "record": { "id": "…", "email": "…", "full_name": "…" },
  "old_record": null
}

record is the new row and old_record is the previous one, which is null on an insert.

Write the route handler

Compare the secret before doing anything else, and use timingSafeEqual rather than === so the comparison does not leak the value a character at a time.

app/api/supabase/route.ts

import { timingSafeEqual } from "node:crypto";
import Courier from "@trycourier/courier";

const courier = new Courier({ apiKey: process.env.COURIER_API_KEY! });

function secretMatches(received: string | null) {
  const expected = process.env.SUPABASE_WEBHOOK_SECRET!;
  if (!received || received.length !== expected.length) return false;
  return timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}

export async function POST(request: Request) {
  if (!secretMatches(request.headers.get("x-webhook-secret"))) {
    return new Response("Unauthorized", { status: 401 });
  }

  const { type, table, record } = await request.json();

  if (type !== "INSERT" || table !== "profiles") {
    return new Response("Ignored", { status: 200 });
  }

  // Supabase's uuid becomes the Courier user id, so both systems agree.
  await courier.profiles.create(record.id, {
    profile: { email: record.email, name: record.full_name },
  });

  await courier.send.message({
    message: {
      to: { user_id: record.id },
      template: "nt_01kx4h2jdafq8bk9aftxak4b40",
      data: { name: record.full_name ?? "there" },
    },
  });

  return new Response("OK", { status: 200 });
}

The trigger already flattened raw_user_meta_data into a column, so the handler reads record.full_name rather than digging through the auth payload.

Add the environment values

.env.local

COURIER_API_KEY=YOUR_COURIER_API_KEY
SUPABASE_WEBHOOK_SECRET=the-same-random-value

Verify

Create a user

Check the webhook ran

Supabase records each delivery with its response code under the webhook in Database → Webhooks. A 401 means the secret does not match.

Confirm the send

Open and confirm the message.

Adapt it for your own tables

The payload shape is the same for every table in public. That makes the same handler useful well beyond signup.

Table and event	What to send
`profiles` INSERT	Welcome
`orders` INSERT	Order confirmation
`orders` UPDATE	A shipping update, comparing `record` to `old_record`
`comments` INSERT	Notify everyone the parent record

The UPDATE row is the one worth planning for. Because old_record carries the previous values, your handler decides whether the change is worth a notification. Firing on every update is how a useful alert becomes noise.

Get started

Send your first message

Build a notification

Send to many people

Send when something happens

Let users choose

Go live

Move to Courier

Send a welcome email from Supabase

What you will build

Prerequisites

Secure it with a shared secret

Set it up

Verify

Adapt it for your own tables

​What you will build

​Prerequisites

​Secure it with a shared secret

​Set it up

​Verify

​Adapt it for your own tables

What you will build

Prerequisites

Secure it with a shared secret

Set it up

Verify

Adapt it for your own tables