Webhooks

Rivanorth Oko can send each confirmed alert to your SIEM, SOAR or ticketing system as a single JSON event.

Overview

When Oko marks a vetted finding as Action required, it sends one outbound HTTPS POST in JSON to your configured endpoint. The event is metadata only: no passwords, hashes, tokens or raw leaked data ever leave Oko. The full incident, including screenshots, exposed data and the written assessment, is reached through the deep link in the event, which requires an authorised login.

Delivery semantics

• One event per request, Content-Type: application/json, a single JSON object per POST.
• Fires on the transition into Action required.
• At most once per finding. A finding that is resolved and later reopened is not sent again.
• At least once on the wire. Transient failures, such as timeouts and 5xx responses, are retried with exponential backoff. There is no ordering guarantee. Use alert_id as the deduplication key if a retry ever double-delivers.
• Delivered over TLS, to a public HTTPS endpoint only.

Payload

{
  "event": "alert.action_required",
  "timestamp": "2026-07-13T09:42:00.000000+00:00",
  "alert_id": "9f1c2a30-4b7e-4c21-8b0a-2f6d9c1e5a44",
  "type": "password",
  "status": "action_required",
  "severity": "high",
  "email": "[email protected]",
  "url": "https://oko.rivanorth.com/alerts/9f1c2a30-4b7e-4c21-8b0a-2f6d9c1e5a44"
}

Field	Type	Meaning	Possible values
event	string	Event kind, distinguishes real alerts from tests	alert.action_required, test.ping
timestamp	string	When the finding was discovered (ISO 8601 with timezone)	e.g. 2026-07-13T09:42:00.000000+00:00
alert_id	string (UUID)	Stable unique id for the finding, use it for deduplication and correlation	any UUID. Test events use 00000000-0000-0000-0000-000000000000
type	string	The kind of exposure. The exposed value itself is never sent	password, username, email, password_hash, api_key, sensitive_data, third_party, ransomware, dark_web, other
status	string	Workflow state at the time of sending	always action_required
severity	string	Risk level	informational, low, medium, high, critical
email	string or null	The exposed email address, when the finding relates to one	an email address, or null
url	string	Deep link to the full incident in Oko, requires an authorised login	e.g. https://oko.rivanorth.com/alerts/<alert_id>

Event types

alert.action_required is a real, vetted finding that needs your attention.

test.ping is a manual connectivity test sent from Oko, carrying placeholder values: the zero UUID and an example.com email address. Filter on event = "test.ping" to keep tests out of your real-alert rules. A test ping looks like this:

{
  "event": "test.ping",
  "timestamp": "2026-07-14T19:21:47.571874+00:00",
  "alert_id": "00000000-0000-0000-0000-000000000000",
  "type": "password",
  "status": "action_required",
  "severity": "high",
  "email": "[email protected]",
  "url": "https://oko.rivanorth.com/alerts/00000000-0000-0000-0000-000000000000"
}

Data handling

The event carries metadata only. It never includes passwords, password hashes, API keys, tokens or raw leaked data. The only personal identifier that can appear is the exposed email address in email, and only when the finding relates to one. All sensitive material stays in Oko and is reached through the login-gated deep link.

Setup and verification

1. Create an HTTPS endpoint, or an HTTP Source in your SIEM or ticketing tool, for example a Sumo Logic HTTP Source.
2. Send the URL to Rivanorth through Support, using the issue type Other and the subject “Webhook”. Rivanorth stores it encrypted at rest and never displays it again.
3. Rivanorth sends a test.ping event so you can confirm your source receives it before go-live.
4. Route and tag the events on your side, for example into a dedicated source category. event, severity and type are the fields to route on.

Support

For integration issues, or to rotate or change your endpoint URL, contact [email protected].