Outbound Webhooks
OrbisID can call your systems when its posture changes: a finding opens, resolves or reopens, a key risk indicator gets worse, or an account is seen as privileged for the first time. Each event is sent as a signed HTTPS request to a URL you choose, so a SIEM, chat bot, ticketing flow or script can react without polling OrbisID. This is available in the Pro and Enterprise editions, and the Administrator role manages subscriptions under Administration > Integrations > Webhooks.
These are different from the real-time events webhooks, which are addresses OrbisID receives identity provider events on. Outbound webhooks are requests OrbisID sends. The API is under /api/v1/outbound-webhooks, and the event schemas are in the OpenAPI document (see below).
Events
| Event | Sent when |
|---|---|
finding.opened | A finding is created for an item a KRI flags |
finding.resolved | A finding is resolved, by a scan confirming the fix or by a person |
finding.reopened | A resolved finding is flagged again |
kri.threshold_breached | A KRI moves into a worse band (green to amber or red, amber to red) between two KRI snapshots |
privileged_account.detected | An account is seen as privileged for the first time |
Events are produced about a minute after the change. Turning webhooks on does not announce what already exists: the first run records the current privileged accounts and KRI snapshot as a starting point, and only later changes produce events. Events are kept for 30 days.
The request body is JSON with the same envelope for every event:
{
"id": "0c5f5a2e-0d1f-4d5e-9d8e-1f7a3f2b9c11",
"type": "finding.opened",
"occurredAt": "2026-10-19T12:00:00Z",
"data": { "findingId": "…", "kriCode": "NOT_IN_PAM_TOOL", "severity": "HIGH", "status": "OPEN", "entityName": "svc-backup", "systemName": "srv01" }
}
id is the same for every subscriber and every retry of one event, so use it to ignore duplicates. data holds the fields of the event type; a value OrbisID does not know is left out. The full field lists are the FindingEventData, KriThresholdEventData and PrivilegedAccountEventData schemas in the OpenAPI document (/api-docs, or the Swagger UI at /swagger-ui.html; administrators only; see API Overview), next to the WebhookEvent envelope. Events carry names, and for findings and accounts the owner's name and email, so send them only to systems that may hold that.
Verify the signature
Every request has these headers:
| Header | Value |
|---|---|
X-OrbisID-Signature | t=<unix seconds>,v1=<hex>, where <hex> is HMAC-SHA256(secret, "<t>.<raw request body>") |
X-OrbisID-Timestamp | The same t |
X-OrbisID-Event | The event type |
X-OrbisID-Delivery | The id of this delivery attempt's record |
Check the signature against the raw body (not re-serialised JSON) with the subscription's secret, compare in constant time, and reject a request whose t is more than five minutes from your clock. The timestamp is part of what is signed, so a captured request cannot be replayed later or with a new timestamp. Each retry is signed afresh with the current time. For example, in Python:
import hmac, hashlib, time
def verify(secret: str, header: str, raw_body: bytes, tolerance=300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
t, v1 = int(parts["t"]), parts["v1"]
if abs(time.time() - t) > tolerance:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, v1)
Answer with any 2xx status within 10 seconds. The response body is ignored.
Create a subscription
- Open Administration > Integrations > Webhooks → Add subscription.
- Enter a name, the
httpsURL, and tick the events you want. - Save. The signing secret is shown once; copy it into the receiver. Replace the secret (key icon) makes a new one and stops the old one working at once.
- Choose Send a test event (paper plane icon): it sends a signed
pingevent and shows the receiver's answer. It is not added to the delivery log.
Where OrbisID will and will not send
To protect your network, OrbisID refuses to send to:
- anything that is not
https, or a URL with a user name or password; - cloud metadata addresses (such as
169.254.169.254), link-local, unspecified, multicast and reserved addresses, always; - loopback, private (
10.x,172.16-31.x,192.168.x, IPv6 unique local) and carrier-grade NAT addresses, unless the subscription is allowed an internal address.
Every address the host name resolves to is checked, when the subscription is saved and again before each delivery. Redirects are never followed. To send to a receiver inside your network, tick Allow an internal (private network) address on that subscription and acknowledge that OrbisID will send requests from its server into your network; this applies to that subscription only and never lifts the metadata block. A host name that is changed to point somewhere else between the check and the connection (DNS rebinding) cannot be ruled out completely, so use a receiver address you control.
Delivery, retries and the log
If the receiver does not answer 2xx, OrbisID tries again after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then marks the delivery Failed. If 10 deliveries in a row fail, the subscription is switched off (the reason is shown and an audit entry is written) and its waiting deliveries are skipped; fix the receiver and use Turn on. A success resets the count.
Delivery log (list icon) shows, newest first, each delivery's event, status (Pending, Delivered, Failed or Skipped), number of attempts, the receiver's last HTTP status or the error, and the next attempt. Send again puts a delivery back in the queue. Deliveries are kept for 30 days.
Creating, changing, deleting, replacing the secret of and automatically switching off a subscription are all recorded in the audit log.