Webhooks

Eventos

Todos os tipos de eventos de webhook disponíveis e suas estruturas de payload.

Envelope de Evento

Todo evento usa a mesma estrutura no nível superior:

json
{
  "event": "user.created",
  "data": { ... },
  "timestamp": "2026-01-15T10:30:00.000Z"
}

Eventos de Usuário

user.created

Disparado quando um novo usuário se cadastra pela primeira vez ou é criado via API.

event.data
json
{
  "event": "user.created",
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "displayName": "John Doe",
      "emailVerified": false,
      "isBanned": false,
      "avatarUrl": null,
      "publicMetadata": null,
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-01-15T10:30:00.000Z"
    }
  },
  "timestamp": "2026-01-15T10:30:00.000Z"
}
user.updated

Disparado quando o perfil ou metadados de um usuário são atualizados.

event.data
json
{
  "event": "user.updated",
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "displayName": "John Doe (Updated)",
      "emailVerified": true,
      "isBanned": false,
      "avatarUrl": "https:0
      10: { 11: "pro" },
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-01-16T09:00:00.000Z"
    }
  },
  "timestamp": "2026-01-16T09:00:00.000Z"
}
user.deleted

Disparado quando uma conta de usuário é excluída permanentemente. O campo data contém um snapshot do usuário antes da exclusão.

event.data
json
{
  "event": "user.deleted",
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "displayName": "John Doe",
      "createdAt": "2026-01-15T10:30:00.000Z"
    }
  },
  "timestamp": "2026-01-20T11:00:00.000Z"
}
user.signin

Disparado quando um usuário entra com sucesso via e-mail/senha ou OAuth.

event.data
json
{
  "event": "user.signin",
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "displayName": "John Doe",
      "emailVerified": true,
      "isBanned": false
    }
  },
  "timestamp": "2026-01-15T10:30:00.000Z"
}
user.signout

Disparado quando um usuário sai explicitamente.

event.data
json
{
  "event": "user.signout",
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "displayName": "John Doe",
      "emailVerified": true,
      "isBanned": false
    }
  },
  "timestamp": "2026-01-15T12:00:00.000Z"
}
user.banned

Disparado quando um usuário é banido por um administrador. Todas as sessões ativas são revogadas.

event.data
json
{
  "event": "user.banned",
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "displayName": "John Doe",
      "isBanned": true
    }
  },
  "timestamp": "2026-01-15T10:30:00.000Z"
}
user.unbanned

Disparado quando o banimento de um usuário é levantado.

event.data
json
{
  "event": "user.unbanned",
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "displayName": "John Doe",
      "isBanned": false
    }
  },
  "timestamp": "2026-01-16T10:00:00.000Z"
}

Eventos de Sessão

session.created

Disparado quando uma nova sessão é criada — no login ou atualização de token.

event.data
json
{
  "event": "session.created",
  "data": {
    "session": {
      "id": "sess_abc123",
      "userId": "usr_abc123",
      "ipAddress": "203.0.113.1",
      "userAgent": "Mozilla/5.0...",
      "createdAt": "2026-01-15T10:30:00.000Z"
    },
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "displayName": "John Doe"
    }
  },
  "timestamp": "2026-01-15T10:30:00.000Z"
}
session.revoked

Disparado quando uma sessão é revogada — no logout ou revogação forçada pelo administrador.

event.data
json
{
  "event": "session.revoked",
  "data": {
    "session": {
      "id": "sess_abc123",
      "userId": "usr_abc123",
      "ipAddress": "203.0.113.1",
      "userAgent": "Mozilla/5.0...",
      "createdAt": "2026-01-15T10:30:00.000Z"
    },
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "displayName": "John Doe"
    }
  },
  "timestamp": "2026-01-15T11:00:00.000Z"
}

Mapeamento de Ação para Evento

A tabela abaixo mostra quais ações do SDK e operações do dashboard disparam quais eventos.

AçãoEventos Disparados
SDK: signup()user.created + session.created
SDK: signin()user.signin + session.created
SDK: signout()user.signout + session.revoked
SDK: Login OAuth (novo usuário)user.created + session.created
SDK: Login OAuth (usuário existente)user.signin + session.created
SDK: refreshTokens()session.revoked + session.created
Dashboard: Banir usuáriouser.banned
Dashboard: Desbanir usuáriouser.unbanned
Dashboard: Excluir usuáriouser.deleted
Dashboard: Atualizar metadadosuser.updated
API Backend: Criar usuáriouser.created
API Backend: Atualizar usuáriouser.updated
API Backend: Excluir usuáriouser.deleted
API Backend: Banir usuáriouser.banned
API Backend: Desbanir usuáriouser.unbanned
SDK: revokeSession()session.revoked

Exemplo de Handler

Um handler de eventos mínimo cobrindo os casos mais comuns de sincronização de usuários:

routes/webhooks.ts
const { event, data } = JSON.parse(req.body.toString());

switch (event) {
  case "user.created":
    await db.users.create({ authonId: data.user.id, email: data.user.email });
    break;
  case "user.updated":
    await db.users.update({ authonId: data.user.id }, { name: data.user.displayName });
    break;
  case "user.deleted":
    await db.users.delete({ authonId: data.user.id });
    break;
  case "user.banned":
    await db.users.update({ authonId: data.user.id }, { suspended: true });
    break;
  case "user.unbanned":
    await db.users.update({ authonId: data.user.id }, { suspended: false });
    break;
  case "session.created":
    console.log(`${data.user.email} signed in from ${data.session.ipAddress}`);
    break;
}
Authon — Plataforma universal de autenticação