Webhook: ricevere gli eventi Riot nei vostri strumenti

1️⃣ Che cos’è un webhook?

L’API di Riot vi permette di andare a recuperare i vostri dati. I webhook fanno l’inverso: Riot invia un evento al vostro strumento (SIEM, SOAR, strumento di ticketing, script interno) non appena si verifica nel vostro workspace. Non avete più bisogno di interrogare l’API a intervalli regolari per sapere se qualcosa è cambiato.

Create e gestite voi stessi i vostri endpoint dalla piattaforma Admin: aggiunta, scelta degli eventi, test, rotazione dei segreti, disattivazione.

💡 Prerequisito: l’accesso ai webhook segue quello all’API, che dipende dal vostro piano. La gestione degli endpoint richiede il ruolo sviluppatore, assegnato dal proprietario dell’account. Vedi Gestire i miei amministratori.

2️⃣ Creare un endpoint

👉 Fase 1: accedete a Impostazioni > API > Webhooks.

👉 Fase 2: aggiungete un endpoint indicando l’URL HTTPS del vostro strumento che riceverà gli eventi.

👉 Fase 3: scegliete i tipi di evento che questo endpoint deve ricevere.

👉 Fase 4: inviate un invio di prova per verificare che il vostro strumento riceva correttamente l’evento prima di farvi affidamento.

👉 Workspace o organizzazione

Un endpoint di workspace riceve soltanto gli eventi di quel workspace.
Un endpoint di organizzazione riceve gli eventi di tutti i workspace dell’organizzazione.

👍 Da sapere: un invio di prova riporta l’header webhook-test: true. Un evento reale non lo riporta mai: filtrate su questo header affinché i vostri test non alimentino la vostra catena di produzione.

3️⃣ Gli eventi disponibili

Oggi sono disponibili due tipi di evento:

inbox_email_analysis.classified: inviato ogni volta che un’e-mail segnalata in Inbox viene classificata, anche in caso di riclassificazione. Il contenuto segue il formato standard OCSF Detection Finding, il che permette di integrarlo in un SIEM o in un SOAR senza mappatura personalizzata.
revoke_drive_item_permission_request.created: inviato quando Riot stabilisce che un accesso concesso a una terza parte su un file deve essere revocato. Gli identificativi forniti nell’evento vi permettono di effettuare la revoca presso il vostro fornitore.

👉 Il dettaglio di ogni evento e del suo contenuto è descritto nella sezione webhook della documentazione.

4️⃣ Sicurezza e affidabilità degli invii

Riot segue la specifica Standard Webhooks: qualsiasi libreria compatibile può verificare e leggere i nostri invii, senza codice specifico.

👉 Verificare la firma

Ogni invio è firmato (HMAC-SHA256) nell’header webhook-signature. Verificatela a partire dal corpo grezzo della richiesta, prima di qualsiasi trasformazione del JSON.
Due segreti possono essere attivi contemporaneamente: potete sostituire un segreto senza interruzione del servizio.

👉 Confermare la ricezione

Il vostro strumento deve rispondere con un codice 2xx in meno di 15 secondi.
L’header webhook-id è identico da un tentativo all’altro: usatelo per non elaborare due volte lo stesso evento.

👉 In caso di errore

Riot effettua fino a 10 tentativi distribuiti su circa 75 ore.
Se un endpoint fallisce più volte di seguito, i suoi amministratori vengono avvisati via e-mail mentre i tentativi continuano, al massimo una volta al giorno.
Riot non disattiva mai un endpoint al vostro posto.

👍 Da sapere: il contenuto degli eventi può arricchirsi di nuovi campi senza preavviso. Ignorate i campi che non conoscete. Una modifica non compatibile (campo eliminato o rinominato, tipo modificato) viene sempre pubblicata con un nuovo tipo di evento, mentre il precedente resta invariato.

Da ricordare

I webhook inviano gli eventi Riot ai vostri strumenti non appena si verificano.
Li gestite voi stessi in Impostazioni > API > Webhooks, con il ruolo sviluppatore.
Testate ogni endpoint prima di farvi affidamento e verificate sempre la firma.
Oggi sono disponibili due eventi: la classificazione di un’e-mail in Inbox e la richiesta di revoca di un accesso a un file.