Verify Supabase signups before the user is created

1. 1
   In PricklyMails

   Create an API key in PricklyMails

   1. In the dashboard, open API Keys and click New key.
   2. Under Environment, pick Test first: the key starts with pm_test_, answers from canned results, bills nothing and contacts no mail server.
   3. Copy the key as soon as it shows: it is shown only once.

   Tip

   The Free plan holds one key: once everything works, revoke the test key, then create the one under Live.

2. 2
   In Supabase

   Add the check to a Supabase Edge Function

   The hook is an HTTP endpoint, here an Edge Function of your project, created and deployed with the Supabase CLI once supabase link points it at the project. The key goes in the function's secrets, never in its code.

   1. Create the function with supabase functions new before-user-created.
   2. Replace the content of its index.ts with the code below.
   3. Store your test key with supabase secrets set PRICKLYMAILS_KEY=pm_test_your_key.
   4. Deploy the function with supabase functions deploy before-user-created --no-verify-jwt.

   The code asks PricklyMails to answer within a few seconds (Prefer: wait) and stops waiting soon after, so a signup never hangs on the answer. It refuses the signup only when the recommendation is remove, and lets it through otherwise: a risky address, no answer in time, an error.

   supabase/functions/before-user-created/index.ts

   import { Webhook } from 'https://esm.sh/standardwebhooks@1.0.0'
   
   const VERIFY_URL = 'https://api.pricklymails.com/api/verify'
   const REFUSAL =
       'This email address cannot receive mail. ' +
       'Check it for a typo, or use another one.'
   
   const hookSecret = Deno.env.get('BEFORE_USER_CREATED_HOOK_SECRET') ?? ''
   const webhook = new Webhook(hookSecret.replace('v1,whsec_', ''))
   
   interface BeforeUserCreatedEvent {
       user: { email?: string }
   }
   
   // Supabase gives the hook 5 seconds: wait 3 for the answer, give up at 3.5.
   async function recommendationFor(
       email: string,
       key: string,
   ): Promise<string | null> {
       try {
           const response = await fetch(VERIFY_URL, {
               method: 'POST',
               headers: {
                   Authorization: `Bearer ${key}`,
                   'Content-Type': 'application/json',
                   Prefer: 'wait=3',
               },
               body: JSON.stringify({ email }),
               signal: AbortSignal.timeout(3500),
           })
           if (200 !== response.status) {
               return null
           }
           const { verification } = await response.json()
           return verification?.recommendation ?? null
       } catch {
           return null
       }
   }
   
   Deno.serve(async (request) => {
       const payload = await request.text()
       const headers = Object.fromEntries(request.headers)
       let event: BeforeUserCreatedEvent
       try {
           event = webhook.verify(payload, headers) as BeforeUserCreatedEvent
       } catch {
           return new Response('Invalid signature', { status: 401 })
       }
       const email = event.user.email
       const key = Deno.env.get('PRICKLYMAILS_KEY') ?? ''
       if (email && 'remove' === (await recommendationFor(email, key))) {
           // Supabase turns a 4xx from the hook into a 500: refuse in a 200 body.
           return Response.json({ error: { http_code: 400, message: REFUSAL } })
       }
       return Response.json({})
   })
   

   How the API answers in one call

   Note

   Supabase Auth calls the hook before any user token exists, hence --no-verify-jwt: the Standard Webhooks signature the code checks is what proves a call comes from Supabase. To keep that setting in your repository, set verify_jwt = false under [functions.before-user-created] in supabase/config.toml.

   Warning

   Keep the refusal on a 200 status, the error in its body: Supabase's hooks guide treats a 400 or 403 from an HTTP hook as an internal error, and answers the signup with a 500 instead of the message.

   SourceSupabase's official help center

   • Before User Created Hook (opens in a new tab)supabase.com
   • Auth Hooks (opens in a new tab)supabase.com
   • Environment variables (opens in a new tab)supabase.com
   • Function Configuration (opens in a new tab)supabase.com
   • Deploy to Production (opens in a new tab)supabase.com
   • supabase functions deploy (opens in a new tab)supabase.com
3. 3
   In Supabase

   Turn on the hook in Supabase

   Supabase signs each call with a secret it generates for the hook, and the function refuses any call it cannot verify, so store the secret before you create the hook. A deployed function reads a new secret at once, with no redeploy.

   1. In the dashboard, go to Authentication then Hooks.
   2. Create a new Before User Created hook.
   3. Select HTTPS as the hook type.
   4. In the URL field, paste the URL of the function, which ends in /functions/v1/before-user-created.
   5. Click Generate Secret.
   6. Store the secret it shows with supabase secrets set BEFORE_USER_CREATED_HOOK_SECRET=v1,whsec_your_secret.
   7. Click Create.

   Tip

   Prefer the dashboard to the CLI? On the Edge Function Secrets page, enter the Key and Value, then click Save, for PRICKLYMAILS_KEY and the hook secret alike.

   SourceSupabase's official help center

   • Auth Hooks (opens in a new tab)supabase.com
   • Configure the Send Email Hook (opens in a new tab)supabase.com
   • Environment variables (opens in a new tab)supabase.com
   • Deploy to Production (opens in a new tab)supabase.com
4. 4
   In Supabase

   Try it with the test key

   1. Sign up with an address that starts with invalid, such as invalid@example.com: the test key answers remove, and the signup is refused.
   2. Sign up with another address, such as valid@example.com: the account is created.
   3. Where you stored the key, replace it with a key created under Live, which starts with pm_live_: from then on, each signup is verified for real and billed like any verification.

What each signup gets

Frequently asked questions