API ReferenceStable v1

Webhooks

Signed event contracts, verification flow, retry semantics, and idempotent consumption.

Last updated Mar 4, 2026

Delivery Contract

Webhooks are asynchronous, signed, and retry-enabled.

POST<your-webhook-endpoint>Signature verification required

Receive score updates, threshold crossings, and runtime risk events.

Verification headers

Header	Required	Description
`X-VaryOn-Event-Id`	yes	Stable event id for idempotency.
`X-VaryOn-Timestamp`	yes	Event timestamp for freshness checks.
`X-VaryOn-Signature`	yes	HMAC signature of canonical payload.

X-VaryOn-Event-Id: evt_123
X-VaryOn-Timestamp: 1700000000
X-VaryOn-Signature: sha256=<hmac>

Verification flow

Validate timestamp tolerance window.
Recompute HMAC over canonical payload.
Reject mismatched signatures.
Enforce idempotency on X-VaryOn-Event-Id.

Example event payload

{
  "event": "threshold.crossed",
  "event_id": "evt_123",
  "occurred_at": "2026-03-04T12:00:00Z",
  "tenant_id": "tenant_abc",
  "entity_id": "agent_42",
  "framework": "drift",
  "score": 34.2,
  "risk_band": "high"
}

Event Types

score.updated
threshold.crossed
runtime.risk.elevated

Retry Semantics

Non-2xx responses are retried with backoff.
Duplicate events are expected under retry.
Consumers must treat event_id as idempotency key.

Always acknowledge quickly and process asynchronously to avoid unnecessary retries.