Send events to a webhook or SIEM Enterprise¶
Purpose: your security team already watches one place. Send what happens in Vidai there, as it happens: changes and sign-ins from the audit log, calls the gateway refused or a guardrail blocked, a provider's model going out of service and back, and Needs attention items as they appear and clear. Each batch is signed, so your side can prove it came from Vidai.
Event webhooks come with Enterprise; what Enterprise includes depends on the features your licence includes. On Community the section says so.
Before you start¶
- You're an organisation admin.
- You have an address that accepts HTTPS posts: your own webhook, or Splunk's HTTP Event Collector
(
…/services/collector/event) and its token. Microsoft Sentinel, Elastic and other SIEMs take a webhook through their HTTP intake (a Logic App, a Logstashhttpinput). - For a webhook, choose a signing secret of at least 16 characters, and give it to whoever runs the receiving side.
Steps¶
- Open System › Settings › Integrations and find Event webhooks and SIEMs.
- Choose Add an event destination.
- Give it a Name, for example Security operations.
- Under Sends to, choose Webhook or Splunk HTTP Event Collector.
- Enter the Address, and the Signing secret (webhook) or HTTP Event Collector token (Splunk). It's stored encrypted and never shown again.
- Under What it receives, keep Every event (every kind, including new ones), or choose Only what I choose and tick the topics.
- Choose Add destination.
- On the new destination, choose Send a test.
What it can receive¶
| Topic | What's in it |
|---|---|
| Calls refused or blocked | A call the gateway refused, or a guardrail blocked or sent to another model; content read |
| Models out of service | A provider's model taken out of service after failures, and back |
| Needs attention | The organisation's Needs attention items as they appear and clear |
| Keys and tokens | Keys issued, changed, turned off and revoked; API tokens and service accounts |
| People, teams and sign-in | People and teams, roles, sign-ins and single sign-on |
| Budgets, cost and prices | Budgets crossed and reached, prices, recompute and exports |
| Rules and compliance | Guardrails, routing, regions, policies, approvals, overrides, access reviews and retention |
| Tamper evidence | Evidence switched on or off, checks and what they found |
| Safety switches and incidents | AI traffic stopped and resumed, guardrails off and on, incidents |
| Applications and agents | Applications, agents and environments |
| Providers and models | Providers, their keys and models added or changed |
| Settings and integrations | Email, integrations and these event destinations |
| Everything else | Any other event |
Check that a batch came from Vidai¶
Each webhook post carries X-Vidai-Timestamp and X-Vidai-Signature: sha256=<hex>: an HMAC-SHA256 made with your
signing secret over the timestamp, a dot, then the body exactly as received. Compute the same, compare, and refuse a
timestamp more than five minutes old.
import hashlib, hmac, time
def from_vidai(secret: bytes, timestamp: str, signature: str, body: bytes) -> bool:
if abs(time.time() - int(timestamp)) > 300:
return False
expected = "sha256=" + hmac.new(secret, timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)
The body is {"events": [...], "sent_at": "..."}, up to 500 events. Each event has its name (event, for example
key.revoked), an id, when it happened, the organisation, who did it (actor), what it concerns (refs, each with its
kind, id and name) and a few details. Answer with any 2xx status once you've stored them. Splunk gets one event per
line, with your collector's token.
Check it worked¶
- After Send a test, the page says "Security operations received the test", or why not, in words.
- What was sent lists each delivery, newest first: when, how many events (or a test), Delivered or Failed with why.
- The destination reads Sending. If your side stops answering, it reads Failing, with how many sends failed in a row and when Vidai tries next.
| When a send fails | What to do |
|---|---|
| It couldn't be reached at that address | Check the address, and that it accepts connections from Vidai |
| It didn't answer in time | Check that it's up, then send a test |
| It refused the signed batch | Check that your side checks signatures with the same secret |
| Splunk refused the token | Check the HTTP Event Collector token, then change the destination |
| That address isn't allowed from Vidai | It's a local or cloud metadata address, or it redirected elsewhere: use another |
| It answered with an error | Vidai sends the events again later, in order |
Pause, change or remove¶
- Pause stops sending without losing anything; Resume catches up from where it stopped.
- Change keeps the kind. Leave the secret blank to keep it; a new address needs the secret again, because Vidai never sends a stored secret to a new place.
- Remove stops sending and deletes its delivery history. Events already delivered stay on your side.
Good to know¶
- Events are sent in order, every few seconds. If your side doesn't answer with success, Vidai keeps them, waits longer each time (up to an hour), then catches up in order.
- A new destination gets events from when it was added, never a backlog.
- Events carry names and ids, never secrets, and never what a call said.