1️⃣ ¿Qué es un webhook?
La API de Riot permite ir a buscar vuestros datos. Los webhooks hacen lo contrario: Riot envía un evento a vuestra herramienta (SIEM, SOAR, herramienta de ticketing, script interno) en cuanto se produce en vuestro workspace. Ya no necesitáis consultar la API a intervalos regulares para saber si algo ha cambiado.
Vosotros mismos creáis y gestionáis vuestros endpoints desde la plataforma Admin: alta, elección de los eventos, prueba, rotación de los secretos, desactivación.
💡 Requisito previo: el acceso a los webhooks sigue al acceso a la API, que depende de vuestro plan. La gestión de los endpoints requiere el rol de desarrollador, asignado por el propietario de la cuenta. Ved Gestionar mis Administradores.
2️⃣ Crear un endpoint
👉 Paso 1: id a Configuración > API > Webhooks.
👉 Paso 2: añadid un endpoint indicando la URL HTTPS de vuestra herramienta que recibirá los eventos. [À VÉRIFIER : libellé exact du bouton d'ajout]
👉 Paso 3: elegid los tipos de evento que debe recibir este endpoint.
👉 Paso 4: enviad un envío de prueba para comprobar que vuestra herramienta recibe correctamente el evento antes de fiaros de él.
👉 Workspace u organización
Un endpoint de workspace recibe únicamente los eventos de ese workspace.
Un endpoint de organización recibe los eventos de todos los workspaces de la organización.
👍 Es bueno saberlo: un envío de prueba lleva el header webhook-test: true. Un evento real nunca lo lleva: filtrad por este header para que vuestras pruebas no alimenten vuestra cadena de producción.
3️⃣ Los eventos disponibles
Hoy hay dos tipos de eventos disponibles:
inbox_email_analysis.classified: se envía cada vez que se clasifica un correo reportado en Inbox, incluso cuando se reclasifica. El contenido sigue el formato estándar OCSF Detection Finding, lo que permite ingerirlo en un SIEM o un SOAR sin una correspondencia personalizada.revoke_drive_item_permission_request.created: se envía cuando Riot determina que un acceso concedido a un tercero sobre un archivo debe revocarse. Los identificadores incluidos en el evento os permiten efectuar la revocación en vuestro proveedor.
👉 El detalle de cada evento y de su contenido se describe en la sección de webhooks de la documentación.
4️⃣ Seguridad y fiabilidad de los envíos
Riot sigue la especificación Standard Webhooks: cualquier biblioteca compatible puede verificar y leer nuestros envíos, sin código específico.
👉 Verificar la firma
Cada envío está firmado (HMAC-SHA256) en el header
webhook-signature. Verificadla a partir del cuerpo sin procesar de la petición, antes de cualquier transformación del JSON.Pueden estar activos dos secretos a la vez: podéis sustituir un secreto sin interrupción del servicio.
👉 Acusar recibo
Vuestra herramienta debe responder con un código
2xxen menos de 15 segundos.El header
webhook-ides idéntico de un intento a otro: usadlo para no procesar dos veces el mismo evento.
👉 En caso de fallo
Riot realiza hasta 10 intentos repartidos en unas 75 horas.
Si un endpoint falla varias veces seguidas, sus administradores reciben un aviso por correo mientras los intentos continúan, como máximo una vez al día.
Riot nunca desactiva un endpoint en vuestro lugar.
👍 Es bueno saberlo: el contenido de los eventos puede enriquecerse con nuevos campos sin previo aviso. Ignorad los campos que no conozcáis. Un cambio incompatible (campo eliminado o renombrado, tipo modificado) se publica siempre con un nuevo tipo de evento, y el anterior se mantiene sin cambios.
Lo que hay que recordar
Los webhooks envían los eventos de Riot a vuestras herramientas en cuanto se producen.
Los gestionáis vosotros mismos en Configuración > API > Webhooks, con el rol de desarrollador.
Probad cada endpoint antes de fiaros de él y verificad siempre la firma.
Hoy hay dos eventos disponibles: la clasificación de un correo en Inbox y la solicitud de revocación de un acceso a un archivo.