Webhooks

Eventos

Todos los tipos de eventos de webhook disponibles y sus estructuras de payload.

Envoltorio del evento

Todos los eventos usan la misma estructura de nivel superior:

json

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

Eventos de usuario

user.created

Se dispara cuando un nuevo usuario se registra por primera vez o es creado mediante la 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

Se dispara cuando el perfil o los metadatos de un usuario son actualizados.

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

Se dispara cuando una cuenta de usuario es eliminada permanentemente. El campo data contiene una instantánea del usuario antes de la eliminación.

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

Se dispara cuando un usuario inicia sesión exitosamente mediante correo/contraseña u 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

Se dispara cuando un usuario cierra sesión explícitamente.

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

Se dispara cuando un administrador bloquea a un usuario. Todas las sesiones activas son revocadas.

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

Se dispara cuando se levanta el bloqueo de un usuario.

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 sesión

session.created

Se dispara cuando se crea una nueva sesión — al iniciar sesión o actualizar el 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

Se dispara cuando se revoca una sesión — al cerrar sesión o por revocación forzada del admin.

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"
}

Mapeo de acciones a eventos

La tabla a continuación muestra qué acciones del SDK y operaciones del panel disparan qué eventos.

Acción	Eventos disparados
SDK: signup()	user.created + session.created
SDK: signin()	user.signin + session.created
SDK: signout()	user.signout + session.revoked
SDK: Inicio de sesión OAuth (usuario nuevo)	user.created + session.created
SDK: Inicio de sesión OAuth (usuario existente)	user.signin + session.created
SDK: refreshTokens()	session.revoked + session.created
Panel: Bloquear usuario	user.banned
Panel: Desbloquear usuario	user.unbanned
Panel: Eliminar usuario	user.deleted
Panel: Actualizar metadatos	user.updated
API backend: Crear usuario	user.created
API backend: Actualizar usuario	user.updated
API backend: Eliminar usuario	user.deleted
API backend: Bloquear usuario	user.banned
API backend: Desbloquear usuario	user.unbanned
SDK: revokeSession()	session.revoked

Ejemplo de handler

Un handler de eventos mínimo que cubre los casos más comunes de sincronización de usuarios:

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;
}