Webhooks : recevoir les événements Riot dans vos outils

1️⃣ Qu'est-ce qu'un webhook ?

L'API Riot vous permet d'aller chercher vos données. Les webhooks font l'inverse : Riot envoie un événement à votre outil (SIEM, SOAR, outil de ticketing, script interne) dès qu'il se produit dans votre workspace. Vous n'avez plus besoin d'interroger l'API à intervalles réguliers pour savoir si quelque chose a changé.

Vous créez et gérez vos endpoints vous-même depuis la plateforme Admin : ajout, choix des événements, test, rotation des secrets, désactivation.

💡 Pré-requis : l'accès aux webhooks suit l'accès à l'API, qui dépend de votre offre. La gestion des endpoints demande le rôle développeur, attribué par le propriétaire du compte. Voir Gérer les Administrateurs.

2️⃣ Créer un endpoint

👉 Étape 1 : rendez-vous dans Paramètres > API > Webhooks.

👉 Étape 2 : ajoutez un endpoint en renseignant l'URL HTTPS de votre outil qui recevra les événements.

👉 Étape 3 : choisissez les types d'événements que cet endpoint doit recevoir.

👉 Étape 4 : envoyez une livraison de test pour vérifier que votre outil reçoit bien l'événement avant de vous y fier.

👉 Workspace ou organisation

Un endpoint de workspace reçoit les événements de ce workspace uniquement.
Un endpoint d'organisation reçoit les événements de tous les workspaces de l'organisation.

👍 Bon à savoir : une livraison de test porte le header webhook-test: true. Un événement réel ne le porte jamais : filtrez sur ce header pour que vos tests n'alimentent pas votre chaîne de production.

3️⃣ Les événements disponibles

Deux types d'événements sont disponibles aujourd'hui :

inbox_email_analysis.classified : envoyé chaque fois qu'un e-mail signalé dans Inbox est classé, y compris lors d'un reclassement. Le contenu suit le format standard OCSF Detection Finding, ce qui permet de l'ingérer dans un SIEM ou un SOAR sans correspondance personnalisée.
revoke_drive_item_permission_request.created : envoyé lorsque Riot détermine qu'un accès accordé à un tiers sur un fichier doit être révoqué. Les identifiants fournis dans l'événement vous permettent d'effectuer la révocation chez votre fournisseur.

👉 Le détail de chaque événement et de son contenu est décrit dans la section webhooks de la documentation.

4️⃣ Sécurité et fiabilité des envois

Riot suit la spécification Standard Webhooks : n'importe quelle bibliothèque compatible peut vérifier et lire nos envois, sans code spécifique.

👉 Vérifier la signature

Chaque envoi est signé (HMAC-SHA256) dans le header webhook-signature. Vérifiez-la à partir du corps brut de la requête, avant toute transformation du JSON.
Deux secrets peuvent être actifs en même temps : vous pouvez remplacer un secret sans interruption de service.

👉 Accuser réception

Votre outil doit répondre par un code 2xx en moins de 15 secondes.
Le header webhook-id est identique d'une tentative à l'autre : utilisez-le pour ne pas traiter deux fois le même événement.

👉 En cas d'échec

Riot fait jusqu'à 10 tentatives réparties sur environ 75 heures.
Si un endpoint échoue plusieurs fois de suite, ses administrateurs sont prévenus par e-mail pendant que les tentatives continuent, au plus une fois par jour.
Riot ne désactive jamais un endpoint à votre place.

👍 Bon à savoir : le contenu des événements peut s'enrichir de nouveaux champs sans préavis. Ignorez les champs que vous ne connaissez pas. Un changement incompatible (champ supprimé ou renommé, type modifié) est toujours publié sous un nouveau type d'événement, l'ancien restant inchangé.

À retenir

Les webhooks envoient les événements Riot vers vos outils dès qu'ils se produisent.
Vous les gérez vous-même dans Paramètres > API > Webhooks, avec le rôle développeur.
Testez chaque endpoint avant de vous y fier, et vérifiez systématiquement la signature.
Deux événements sont disponibles aujourd'hui : la classification d'un e-mail dans Inbox et la demande de révocation d'un accès à un fichier.