GET /api/v2/events et reçoit les événements sous forme de flux d’événements envoyés par le serveur (SSE). Vous contrôlez quand vous connecter, comment reprendre après une déconnexion et à quel rythme consommer les événements.
Cette approche est utile lorsque vous devez :
- Traiter les événements à votre propre rythme sans mettre en place un webhook endpoint.
- Rejouer les événements à partir d’un moment précis pour le remplissage rétroactif ou la récupération.
- Intégrer des systèmes qui privilégient l’interrogation périodique plutôt qu’une distribution par envoi.
Fonctionnement de l’Events API
Lorsque votre application se connecte à l’Events API, elle reçoit un flux de messages SSE. Chaque message comprend un champid qui sert d’offset. Si la connexion est interrompue, votre application se reconnecte et fournit le dernier offset reçu. Auth0 reprend alors la transmission à partir de ce point, de sorte qu’aucun événement n’est perdu.
Le flux SSE comprend les types de messages suivants :
Exemple de flux SSE
Prérequis
Avant de commencer, assurez-vous d’avoir :-
Un tenant Auth0 avec Events activé. Le nombre de connexions Event Stream disponibles dépend de votre plan :
-
Un jeton d’accès à l’API de gestion avec la portée
read:events. Pour en savoir plus, consultez Jetons d’accès à l’API de gestion.
Se connecter à l’API Events
Ouvrez une connexion SSE au point de terminaison des événements de votre tenant. L’exemple suivant utilisecurl :
- Auth0 CLI
- cURL
Vous utilisez Auth0 CLI? Si ce n’est pas déjà fait, configurez et authentifiez votre session CLI avant d’exécuter cette commande.
Paramètres de requête
Utilisez les paramètres de requête pour filtrer le flux ou le reprendre :- Auth0 CLI
- cURL
Reprendre après une déconnexion
Les connexions SSE peuvent être interrompues pour de nombreuses raisons : problèmes de réseau, expiration du token ou rotation des connexions côté serveur (Auth0 ferme périodiquement les connexions pour la répartition de charge — généralement toutes les quelques minutes). Les bibliothèques clientes SSE standard gèrent cela de façon transparente en se reconnectant et en envoyant le dernier offset. Il existe deux façons de fournir l’offset lors de la reconnexion :- En-tête
Last-Event-ID— le mécanisme standard de reconnexion SSE. La plupart des bibliothèques clientes SSE définissent automatiquement cet en-tête lors de la reconnexion. - Paramètre de requête
from— utilisez-le lorsque votre client ne prend pas en charge l’en-têteLast-Event-ID.
Last-Event-ID est prioritaire.
- Auth0 CLI
- cURL
Enregistrez la valeur
id la plus récente de chaque message (y compris les messages offset-only) dans un stockage persistant. Si votre application redémarre, utilisez l’offset enregistré pour reprendre la livraison là où elle s’était arrêtée.Gérer les types de messages
Événements réels
Les messages dont le champevent correspond à un type d’événement connu (par exemple, user.created) contiennent le payload complet de l’événement dans le champ data. Analysez le JSON et traitez l’événement selon votre logique d’affaires.
Messages offset-only
Auth0 envoie des messages offset-only à intervalles réguliers (à la fréquence du heartbeat) pour faire avancer votre position dans le stream. Ces messages ne contiennent pas de payload d’événement. Mettez à jour l’offset enregistré lorsque vous les recevez afin qu’une reconnexion ultérieure ne rejoue pas les événements que vous avez déjà dépassés.
Messages d’erreur
Un messageevent: error signale un problème fatal, comme un offset expiré ou un problème côté serveur. Après réception de ce message, le flux se ferme. Votre application devrait consigner l’erreur, puis se reconnecter en utilisant l’offset approprié ou un nouveau from_timestamp.
Signaux de vie
Les lignes commençant par: sont des commentaires SSE servant de signaux de vie. Elles permettent de maintenir la connexion active à travers les proxys et les répartiteurs de charge. Aucun traitement n’est requis.
Rotation des connexions côté serveur
Auth0 ferme périodiquement les connexions SSE pour répartir la charge (généralement toutes les quelques minutes). Il s’agit d’un comportement attendu, et non d’une erreur. Les bibliothèques clientes SSE standard (y compris lepackage npm eventsource) se reconnectent automatiquement à l’aide de l’en-tête Last-Event-ID, de sorte que votre application reprend à partir du bon offset sans perdre d’événements.
Si vous développez un client SSE personnalisé, assurez-vous qu’il gère correctement les interruptions de connexion en enregistrant le dernier offset et en se reconnectant avec celui-ci.
Mettre en place un consommateur
L’exemple Node.js suivant présente un consommateur minimal de l’Events API qui traite les événements et enregistre l’offset dans un fichier.Le package npm
eventsource implémente le protocole SSE et gère automatiquement la reconnexion à l’aide de l’en-tête Last-Event-ID. Si vous utilisez une autre bibliothèque SSE, vérifiez qu’elle prend en charge la reconnexion automatique et la transmission de l’offset.