Reference

Webhooks

Subscribe to real-time notifications when scores change, events are ingested, or credentials are updated. Webhooks use HMAC-SHA256 signature verification.

Create a subscription

Register a webhook URL with one or more event types. The response includes an HMAC secret for verifying incoming payloads.

TypeScript

const sub = await client.webhooks.create({

url: 'https://acme.com/webhooks/credian',

events: ['score.changed', 'event.ingested'],

})

// sub.secret = 'whsec_...' — save this for verification

Webhook event types

Event	Description
score.changed	Agent trust score has been recalculated
event.ingested	A new behavioral event was accepted
credential.issued	A trust credential was issued
credential.revoked	A trust credential was revoked
agent.status_changed	Agent status changed (active, suspended, deactivated)

Payload format

JSON

{
  "id": "evt_a1b2c3d4",
  "type": "score.changed",
  "timestamp": "2026-06-15T11:00:00Z",
  "data": {
    "agentId": "a1b2c3d4-...",
    "previousScore": 100,
    "newScore": 112,
    "classification": "untrusted",
    "triggeredBy": "event_ingested"
  }
}

Signature verification

Every webhook delivery includes an X-Credian-Signature header containing an HMAC-SHA256 signature of the raw request body. Use the SDK utility to verify it.

TypeScript

import { verifyWebhookSignature } from 'credian'

app.post('/webhooks/credian', (req, res) => {

const isValid = verifyWebhookSignature(

req.body,

req.headers['x-credian-signature'],

webhookSecret

)

if (!isValid)

return res.status(401).send('Invalid signature')

// Handle event...

})

Retry behavior

Failed deliveries (non-2xx response) are retried with exponential backoff. After 5 consecutive failures, the subscription is paused. After 10 failures, it is disabled. You can re-enable a paused or disabled subscription from the dashboard.

Failure count	Status	Action
1 - 4	active	Retries with exponential backoff
5 - 9	paused	Deliveries stop; re-enable from dashboard
10+	disabled	Requires manual re-creation