Webhooks: receive Riot events in your tools

1️⃣ What is a webhook?

The Riot API lets you fetch your data. Webhooks do the opposite: Riot sends an event to your tool (SIEM, SOAR, ticketing tool, internal script) as soon as it happens in your workspace. You no longer need to poll the API at regular intervals to find out whether something has changed.

You create and manage your endpoints yourself from the Admin platform: adding, choosing events, testing, rotating secrets, disabling.

💡 Prerequisite: webhook access follows API access, which depends on your plan. Managing endpoints requires the developer role, assigned by the account owner. See Manage my Admins.

2️⃣ Create an endpoint

👉 Step 1: go to Settings > API > Webhooks.

👉 Step 2: add an endpoint by entering the HTTPS URL of your tool that will receive the events.

👉 Step 3: choose the event types this endpoint should receive.

👉 Step 4: send a test delivery to check that your tool receives the event properly before relying on it.

👉 Workspace or organisation

A workspace endpoint receives the events of that workspace only.
An organisation endpoint receives the events of all the workspaces in the organisation.

👍 Good to know: a test delivery carries the header webhook-test: true. A real event never carries it: filter on this header so that your tests do not feed your production pipeline.

3️⃣ Available events

Two event types are available today:

inbox_email_analysis.classified: sent every time an email reported in Inbox is classified, including when it is reclassified. The content follows the standard OCSF Detection Finding format, so it can be ingested into a SIEM or a SOAR without custom mapping.
revoke_drive_item_permission_request.created: sent when Riot determines that access granted to a third party on a file should be revoked. The identifiers provided in the event let you carry out the revocation with your provider.

👉 Details of each event and its content are described in the webhooks section of the documentation.

4️⃣ Delivery security and reliability

Riot follows the Standard Webhooks specification: any compatible library can verify and read our deliveries, with no specific code.

👉 Verify the signature

Each delivery is signed (HMAC-SHA256) in the webhook-signature header. Verify it against the raw body of the request, before any JSON transformation.
Two secrets can be active at the same time: you can replace a secret without any service interruption.

👉 Acknowledge receipt

Your tool must respond with a 2xx code in under 15 seconds.
The webhook-id header is the same from one attempt to the next: use it to avoid processing the same event twice.

👉 If delivery fails

Riot makes up to 10 attempts spread over about 75 hours.
If an endpoint fails several times in a row, its administrators are notified by email while the attempts continue, at most once a day.
Riot never disables an endpoint on your behalf.

👍 Good to know: the content of events may gain new fields without notice. Ignore the fields you do not recognise. A breaking change (field removed or renamed, type modified) is always published under a new event type, and the old one remains unchanged.

Key takeaways

Webhooks send Riot events to your tools as soon as they happen.
You manage them yourself in Settings > API > Webhooks, with the developer role.
Test each endpoint before relying on it, and always verify the signature.
Two events are available today: the classification of an email in Inbox and the request to revoke access to a file.