Skip to main content

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​

EventSent when
finding.openedA finding is created for an item a KRI flags
finding.resolvedA finding is resolved, by a scan confirming the fix or by a person
finding.reopenedA resolved finding is flagged again
kri.threshold_breachedA KRI moves into a worse band (green to amber or red, amber to red) between two KRI snapshots
privileged_account.detectedAn 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:

HeaderValue
X-OrbisID-Signaturet=<unix seconds>,v1=<hex>, where <hex> is HMAC-SHA256(secret, "<t>.<raw request body>")
X-OrbisID-TimestampThe same t
X-OrbisID-EventThe event type
X-OrbisID-DeliveryThe 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​

  1. Open Administration > Integrations > Webhooks → Add subscription.
  2. Enter a name, the https URL, and tick the events you want.
  3. 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.
  4. Choose Send a test event (paper plane icon): it sends a signed ping event 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.