Read API

Every delivery is a POST with this body:

{
  "id": "0f3a…",                 // Alethexis-Event-Id
  "type": "section.closed",
  "created_at": "2026-09-18T09:12:03.412Z",
  "api_version": "v1",
  "data": { "account_id": "…", "section_id": "GOB-2", "status": "complete", "closed_at": "…" }
}

Headers: Alethexis-Signature, Alethexis-Event-Id, Alethexis-Event-Type and User-Agent: Alethexis-Webhooks/1.

Signature

The v1 value is the HMAC-SHA256 of the timestamp, a dot and the exact body you receive, using the endpoint secret. Compare in constant time and reject anything more than five minutes old.

Verification:

// Node.js
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(rawBody, header, secret, toleranceSeconds = 300) {
  const [t, v1] = header.split(',').map((part) => part.split('=')[1]);
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false;

  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
  const received = Buffer.from(v1, 'hex');
  return expected.length === received.length && timingSafeEqual(expected, received);
}

# Python
import hashlib, hmac, time

def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > tolerance:
        return False

    expected = hmac.new(
        secret.encode(), f'{parts["t"]}.'.encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Retries

A 2xx response is a good delivery; anything else, or a 10-second timeout, is a failure. The first attempt is made straight away; if it fails, it is retried one hour after the failure, and then two, four and eight hours after the previous failure. That makes five attempts in total: after the fifth failure the delivery is exhausted and you can replay it by hand from Settings → Integrations → Webhooks. Exhausted deliveries appear in Alethexis’s internal daily report.

Idempotency

Alethexis-Event-Id identifies the event, not the attempt: a retry repeats the same identifier. Keep the ones you have processed and discard repeats. The same event arrives once per subscribed endpoint.

v1 catalogue

v1 has nine events. Each endpoint receives only the events it subscribes to.

What a webhook never carries

Payloads carry identifiers, states and dates. Never names, free text or personal data. The detail is read afterwards with the API. Until 18 September 2026 some events also carried the name of the system or tool; they no longer do, because that name is written by your organisation and nothing stops it from containing a person’s.

Getting the detail from a webhook

Every payload carries the identifiers you need to ask the API for the rest with your key. A `system_id` gives you its classification, its controls and its evidence:

# data.system_id from a system.created / system.reclassified payload
SYSTEM_ID="8f2c…"

curl -H "Authorization: Bearer $ALETHEXIS_API_KEY" \
  "https://www.alethexis.com/api/v1/classifications?system_id=$SYSTEM_ID&current=true"

curl -H "Authorization: Bearer $ALETHEXIS_API_KEY" \
  "https://www.alethexis.com/api/v1/controls?system_id=$SYSTEM_ID"

curl -H "Authorization: Bearer $ALETHEXIS_API_KEY" \
  "https://www.alethexis.com/api/v1/evidence?system_id=$SYSTEM_ID"

Risks do not have their own API resource yet: from `risk.high_registered` you can resolve the system through its `system_id`, and the risk itself is consulted in the platform.

Receiver requirements

The URL must be https and resolve to a public address: webhooks are not delivered to private or internal addresses. Respond within 10 seconds; if you need longer, accept the delivery and process it afterwards.