Technical Reference

Webhooks

Receive real-time HTTP callbacks when authentication events occur in the CAS system.

How It Works

When an event fires — such as a user login, logout, or failed authentication attempt — CAS sends a POST request to your registered webhook URL with a JSON payload describing the event. All payloads include an HMAC-SHA256 signature in the X-CAS-Signature header for verification.

Real-Time

Events fire within milliseconds of the triggering action.

Auto Retry

Failed deliveries are retried 3 times with exponential backoff.

Signed

HMAC-SHA256 signatures prevent spoofing and tampering.

Event Types

Event	Description	Trigger
`user.login`	Successful authentication	SSO token issued
`user.logout`	User session ended	Token invalidated
`user.login_failed`	Failed login attempt	Invalid credentials
`user.locked`	Account locked out	5 failed attempts
`user.2fa_enabled`	2FA activated	User enabled TOTP
`token.expired`	Token reached expiry	JWT TTL elapsed
`client.registered`	New client system added	Admin action

Payload Format

user.login event payload application/json

{
  "event": "user.login",
  "timestamp": "2026-03-10T12:00:00Z",
  "data": {
    "user_id": 42,
    "email": "[email protected]",
    "ip_address": "192.168.1.10",
    "user_agent": "Mozilla/5.0 ...",
    "client_system": "customer-portal",
    "2fa_used": true
  }
}

Signature Verification

Every webhook request contains an X-CAS-Signature header. Verify it before processing the payload.

PHP verification example

$payload   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_CAS_SIGNATURE'];
$expected  = hash_hmac('sha256', $payload, $webhookSecret);

if (hash_equals($expected, $signature)) {
    // Safe to process
    $event = json_decode($payload, true);
}

Registering a Webhook

POST /api/webhooks

{
  "url": "https://your-app.com/webhooks/cas",
  "events": ["user.login", "user.logout", "user.locked"],
  "secret": "whsec_your_signing_secret"
}

Security — Always verify the X-CAS-Signature header before processing events. Never trust unverified payloads.