Auth event hooks

An auth event hook sends a signed POST to your URL when something happens to one of your app users — to sync a CRM, send a welcome email or alert on suspicious sign-ins. Add them under Authentication › Auth hooks or from code.

await sovaria.auth.eventHooks.create({
  name: 'crm-sync',
  url: 'https://api.example.com/hooks/sovaria',
  events: ['auth.user.registered', 'auth.user.email_verified'],
  secret: process.env.SOVARIA_HOOK_SECRET,   // used to sign each call
})

#Check the signature

Each call carries X-Sovaria-Signature: sha256=<hex>, the HMAC-SHA-256 of the raw request body with your secret. Compare it before trusting the body:

import crypto from 'node:crypto'

export function isFromSovaria(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
  return header?.length === expected.length && crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected))
}

#Delivery

• Each call waits up to 10 seconds for a 2xx. On a network error or another status it is retried 3 times (after about 0.5, 1 and 2 seconds), then marked failed.
• Return 2xx quickly and do slow work afterwards; make your handler safe to receive the same event twice.
• URLs must be public HTTPS addresses; private and internal addresses are refused, also if a hostname later resolves to one.
• Secrets are encrypted at rest; a hook's last error is kept as http_<status> or network, never the response body.
• At most 20 hooks per project.

To add custom claims to users' tokens instead, use the JWT hook in Authentication settings reference.