ASN — Agent Security Number

Configuration

Webhooks are configured at the platform level. When you register a platform with ASN, you provide a webhook URL and receive a webhook secret for signature verification.

webhook_url — Your HTTPS endpoint that receives POST requests

webhook_secret — HMAC secret for verifying payload authenticity

Event Types

agent.registered — New agent registered on your platform

agent.updated — Agent profile updated

agent.deactivated — Agent deactivated by operator

agent.ownership_verified — Agent ownership verification completed

trust.updated — Trust score recomputed for an agent

trust.threshold_crossed — Agent crossed a trust score threshold (up or down)

incident.created — New incident reported for an agent

incident.resolved — Incident resolved

operator.kyc_verified — Operator completed KYC verification

Payload Format

All webhook payloads follow a consistent envelope:

POST /your-webhook-url
Content-Type: application/json
X-ASN-Signature: sha256=a1b2c3d4e5f6...
X-ASN-Timestamp: 1710763200
X-ASN-Event: trust.updated

{
  "id": "evt_550e8400-e29b-41d4...",
  "type": "trust.updated",
  "created_at": "2026-03-18T12:00:00Z",
  "data": {
    "asn": "ASN-2026-0384-7721-A",
    "previous_score": 93.8,
    "new_score": 94.1,
    "dimensions": {
      "reliability": 96.2,
      "accuracy": 93.8,
      "safety": 95.0,
      "speed": 88.4,
      "consistency": 97.1
    }
  }
}

Signature Verification

Every webhook request includes an HMAC-SHA256 signature in the X-ASN-Signature header. Always verify this before processing the payload.

import crypto from 'crypto';

function verifyWebhook(payload, signature, secret) {
  const timestamp = /* from X-ASN-Timestamp header */;
  const body = timestamp + '.' + JSON.stringify(payload);
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature.replace('sha256=', '')),
    Buffer.from(expected)
  );
}

Retry Policy

If your endpoint returns a non-2xx status code or times out (30 seconds), ASN retries with exponential backoff:

Attempt 1: Immediate

Attempt 2: 1 minute

Attempt 3: 5 minutes

Attempt 4: 30 minutes

Attempt 5: 2 hours (final)

After 5 failed attempts, the event is marked as failed. Repeatedly failing webhooks may be automatically disabled.

Example: Incident Alert

{
  "id": "evt_a1b2c3d4...",
  "type": "incident.created",
  "created_at": "2026-03-18T15:00:00Z",
  "data": {
    "incident_id": "inc-uuid-...",
    "asn": "ASN-2026-0384-7721-A",
    "title": "Elevated error rate detected",
    "severity": "warning",
    "status": "open",
    "description": "Agent error rate exceeded 5% threshold"
  }
}

← Operators API JavaScript SDK →