Consumir eventos con la Events API

Extraiga eventos de Auth0 a su propio ritmo mediante la Events API basada en Server-Sent Events (SSE).

La Events API proporciona una alternativa basada en extracción a los flujos de eventos. En lugar de que Auth0 envíe eventos a un destino, su aplicación abre una conexión de larga duración a GET /api/v2/events y recibe eventos como un flujo de Server-Sent Events (SSE). Puede controlar cuándo conectarse, cómo reanudar la conexión después de una desconexión y con qué rapidez consumir los eventos.

Este enfoque es útil cuando necesita:

• Procesar eventos a su propio ritmo sin tener que implementar un endpoint de webhook.
• Reproducir eventos desde un momento específico para completar datos históricos o recuperarse de errores.
• Integrarse con sistemas que prefieren el sondeo en lugar de la entrega push.

​

Cómo funciona la Events API

Cuando su aplicación se conecta a la Events API, recibe un flujo de mensajes SSE. Cada mensaje incluye un campo id que actúa como un offset. Si la conexión se interrumpe, su aplicación se vuelve a conectar y proporciona el último offset que recibió. Auth0 reanuda la entrega desde ese punto, por lo que no se pierde ningún evento.

El flujo de SSE incluye los siguientes tipos de mensajes:

Tipo de mensaje	Propósito
:connected	Confirma que la conexión se ha establecido. Se trata de un comentario de SSE, no de un evento de datos.
retry: <ms>	Indica al cliente SSE cuánto tiempo debe esperar antes de volver a conectarse tras una desconexión.
event: <type> (por ejemplo, user.created)	Un evento real con la carga útil completa en el campo data.
event: offset-only	Un marcador de progreso que se envía a intervalos regulares (con la frecuencia del heartbeat). Actualiza el offset sin entregar datos de eventos.
: seguido de texto (por ejemplo, : heartbeat)	Un comentario keep-alive que evita que los proxies y los balanceadores de carga cierren conexiones inactivas. No requiere ninguna acción.
event: error	Un error terminal. El flujo se cierra después de este mensaje.

​

Ejemplo de flujo SSE

:connected

retry: 2000

event: user.created
id: MTIzNDIzNDEzCg==
data: {"offset":"MTIzNDIzNDEzCg==","event":{"id":"evt_abc123","type":"user.created","time":"2025-06-01T12:00:00Z","data":{"object":{"user_id":"auth0|123","email":"[e-mail]"}}}}

event: offset-only
id: 4LcuTXmVDASuNRQt
data: {"offset":"4LcuTXmVDASuNRQt"}

: heartbeat

event: user.updated
id: NTY3ODkwMTIzCg==
data: {"offset":"NTY3ODkwMTIzCg==","event":{"id":"evt_def456","type":"user.updated","time":"2025-06-01T12:05:00Z","data":{"object":{"user_id":"auth0|123","email":"[e-mail]"}}}}

​

Requisitos previos

Antes de comenzar, asegúrate de tener:

• Un inquilino de Auth0 con Events habilitado. La cantidad de conexiones de flujo de eventos disponibles depende de tu plan:

  Plan	Límite de conexiones
  Free	1
  Self-service	4
  Enterprise	8

• Un token de acceso de la Management API con el scope read:events. Para obtener más información, consulta Management API Access Tokens.

​

Conéctese a la Events API

Abra una conexión SSE con el endpoint de eventos de su inquilino. En el siguiente ejemplo se usa curl:

curl -N --http2 \
    -H "Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN" \
    -H "Accept: text/event-stream" \
    "https://YOUR_DOMAIN/api/v2/events"

​

Parámetros de consulta

Use parámetros de consulta para filtrar o reanudar el flujo:

Parameter	Type	Description
from	string	Un offset devuelto en un campo id anterior. La entrega se reanuda después de este offset.
from_timestamp	string	Una marca de tiempo ISO 8601. Devuelve eventos que ocurrieron en ese momento o después. Es mutuamente excluyente con from. Se recomienda usarlo para la configuración inicial o para reproducir eventos desde un momento conocido; para el consumo continuo, prefiera reanudar con from, ya que los offsets son más precisos.
event_type	string	El tipo de evento que se incluirá. Repita el parámetro para cada tipo (por ejemplo, event_type=user.created&event_type=user.updated).

curl -N --http2 \
    -H "Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN" \
    -H "Accept: text/event-stream" \
    "https://YOUR_DOMAIN/api/v2/events?event_type=user.created&event_type=user.updated&from_timestamp=2025-06-01T00:00:00Z"

​

Reanudar después de una desconexión

Las conexiones SSE pueden interrumpirse por muchos motivos: problemas de red, vencimiento del token o rotación de conexiones del lado del servidor (Auth0 cierra periódicamente las conexiones para equilibrar la carga; por lo general, cada pocos minutos). Las bibliotecas cliente SSE estándar gestionan esto de forma transparente, reconectándose y enviando el último offset.

Hay dos formas de proporcionar el offset al volver a conectarse:

• Encabezado Last-Event-ID — el mecanismo estándar de reconexión de SSE. La mayoría de las bibliotecas cliente SSE establecen este encabezado automáticamente al volver a conectarse.
• Parámetro de consulta from — úselo cuando su cliente no admita el encabezado Last-Event-ID.

Si se proporcionan ambos, el encabezado Last-Event-ID tiene prioridad.

curl -N --http2 \
    -H "Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN" \
    -H "Accept: text/event-stream" \
    -H "Last-Event-ID: MTIzNDIzNDEzCg==" \
    "https://YOUR_DOMAIN/api/v2/events"

Guarda el valor más reciente de id de cada mensaje (incluidos los mensajes offset-only) en almacenamiento persistente. Si tu aplicación se reinicia, usa el offset guardado para reanudar la entrega desde donde se interrumpió.

​

Procesar tipos de mensajes

​

Eventos reales

Los mensajes cuyo campo event coincide con un tipo de evento conocido (por ejemplo, user.created) contienen la carga útil completa del evento en el campo data. Analiza el JSON y procesa el evento según tu lógica de negocio.

​

Mensajes solo de offset

Auth0 envía mensajes offset-only a intervalos regulares (según la frecuencia de heartbeat) para avanzar su posición en el flujo. Estos mensajes no contienen una carga útil de evento. Actualice el offset almacenado cuando los reciba para que una reconexión futura no vuelva a reproducir eventos que ya haya superado.

​

Mensajes de error

Un mensaje event: error indica un error terminal, como un offset vencido o un problema del lado del servidor. Después de recibir este mensaje, el flujo se cierra. Su aplicación debe registrar el error y, a continuación, volver a conectarse con el offset adecuado o con un from_timestamp nuevo.

​

Latidos

Las líneas que comienzan con : son comentarios de SSE que se usan como latidos. Mantienen la conexión activa a través de proxies y balanceadores de carga. No se requiere ningún procesamiento.

​

Rotación de conexiones del lado del servidor

Auth0 cierra periódicamente las conexiones SSE para equilibrar la carga (normalmente, cada pocos minutos). Este comportamiento es el esperado, no un error. Las bibliotecas cliente SSE estándar (incluido el paquete npm eventsource) se reconectan automáticamente mediante el encabezado Last-Event-ID, por lo que su aplicación reanuda el procesamiento desde el offset correcto sin perder eventos.

Si crea un cliente SSE personalizado, asegúrese de que gestione las caídas de conexión correctamente; para ello, conserve el offset más reciente y vuelva a conectarse con él.

​

Implementar un consumidor

El siguiente ejemplo de Node.js muestra un consumidor mínimo de la Events API que procesa eventos y guarda el offset en un archivo.

const EventSource = require("eventsource");
const fs = require("fs");

const OFFSET_FILE = "./offset.txt";
const AUTH0_DOMAIN = "YOUR_DOMAIN";
const TOKEN = "YOUR_MANAGEMENT_API_TOKEN";

function loadOffset() {
    try {
        return fs.readFileSync(OFFSET_FILE, "utf8").trim();
    } catch {
        return null;
    }
}

function saveOffset(offset) {
    fs.writeFileSync(OFFSET_FILE, offset);
}

function connect() {
    const offset = loadOffset();
    const params = new URLSearchParams();
    params.append("event_type", "user.created");
    params.append("event_type", "user.updated");
    params.append("event_type", "user.deleted");

    if (offset) {
        params.append("from", offset);
    }

    const url = `https://${AUTH0_DOMAIN}/api/v2/events?${params.toString()}`;

    const es = new EventSource(url, {
        headers: {
            "Authorization": `Bearer ${TOKEN}`
        }
    });

    // Procesar eventos reales
    for (const type of ["user.created", "user.updated", "user.deleted"]) {
        es.addEventListener(type, (msg) => {
            const payload = JSON.parse(msg.data);
            console.log(`Received ${type}:`, payload.event.id);

            // Procesar el evento aquí

            saveOffset(msg.lastEventId);
        });
    }

    // Procesar marcadores de progreso de solo offset
    es.addEventListener("offset-only", (msg) => {
        saveOffset(msg.lastEventId);
    });

    // Gestionar errores terminales
    es.addEventListener("error", (msg) => {
        if (msg.data) {
            const errorPayload = JSON.parse(msg.data);
            console.error("Stream error:", errorPayload.error);
        }
        es.close();

        // Reconectar tras un retraso
        setTimeout(connect, 5000);
    });
}

connect();

El paquete npm eventsource implementa el protocolo SSE y gestiona la reconexión automáticamente mediante el encabezado Last-Event-ID. Si usa una biblioteca SSE diferente, verifique que admita la reconexión automática y el reenvío del offset.

​

Respuestas de error

La Events API devuelve códigos de estado HTTP estándar cuando no se puede establecer la conexión:

Código de estado	Significado
200	Conexión establecida. Los eventos comienzan a transmitirse.
400	Solicitud no válida. El valor de offset no tiene el formato correcto o el tipo de evento solicitado no se admite.
401	Falta el token de acceso o no es válido.
403	El token de acceso no incluye el scope read:events.
410	El offset ha expirado. Usa un valor from_timestamp para reanudar desde un momento específico.
429	Se superó el límite de tasa. Espera y vuelve a intentarlo usando el intervalo de la cabecera Retry-After.

​

Más información

• Tipos de eventos
• Crear un flujo de eventos
• Prácticas recomendadas para eventos
• Tokens de acceso para la Management API