Webhooks

Webhooks & Real-Time Event Streaming

Subscribe to authorisation events and have them delivered to any HTTP endpoint in real time. Every payload is HMAC-SHA256 signed with your webhook secret.

Supported Event Types

Event	Fires when...
decision.block	Any agent action is blocked
decision.escalate	A decision requires human review
decision.allow	An action is approved (opt-in, high volume)
breakglass.triggered	Emergency override activated
breakglass.deactivated	Emergency override ended
federation.link_proposed	New cross-org trust link proposed
federation.token_issued	Cross-org token minted
policy.deployed	A policy pack goes live
policy.rollback	A policy pack is rolled back
agent.registered	New agent registered
agent.trust_changed	Agent trust score crosses a threshold
rbac.role_assigned	A role is assigned to an agent
temporal.window_opened	A JIT access window opens
temporal.window_expired	A JIT access window closes

Create a Webhook

from xybern import Xybern

client = Xybern(api_key="xb_your_key")

hook = client.webhooks.create(
    url="https://hooks.slack.com/services/T0/B0/xxx",
    events=["decision.block", "breakglass.triggered"],
    description="Slack alerts for security events",
)
# Save hook["webhook"]["secret"] to verify signatures later
print(hook["webhook"]["webhook_id"])

Payload Format

{
  "event": "decision.block",
  "timestamp": "2026-04-01T19:32:14.003Z",
  "workspace_id": "f5300764...",
  "data": {
    "decision_id": "enf_a1b2c3d4e5f6",
    "agent_id": "agent_35c86445e7e2",
    "action_type": "admin:delete_workspace",
    "decision": "block",
    "decision_path": "rbac",
    "reasoning": "Action not allowed by agent roles",
    "trust_score": 22.8
  }
}

Signature Verification

Every delivery includes an X-Xybern-Signature header. Verify it server-side:

import hmac, hashlib

def verify_webhook(payload_bytes, signature_header, secret):
    expected = hmac.new(
        secret.encode(), payload_bytes, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature_header)

Retry Policy

Failed deliveries are retried with exponential backoff (1s, 2s, 4s, 8s, 16s). After 50 consecutive failures, the webhook is auto-disabled. Re-enable it via the API or dashboard.

REST API Reference

Method	Endpoint	Description
POST	/v1/enforce/webhooks	Create a subscription
GET	/v1/enforce/webhooks	List subscriptions
GET	/v1/enforce/webhooks/:id	Get a subscription
PUT	/v1/enforce/webhooks/:id	Update a subscription
DELETE	/v1/enforce/webhooks/:id	Delete a subscription
POST	/v1/enforce/webhooks/:id/test	Send a test event
GET	/v1/enforce/webhooks/:id/deliveries	List delivery history
POST	/v1/enforce/webhooks/:id/rotate-secret	Rotate signing secret
GET	/v1/enforce/webhooks/stats	Webhook statistics