Skip to Content
Documentation menu

Guides

Webhooks

Every sealed audit record (each decision, approval, consent change, configuration change) can be pushed to an HTTPS endpoint you run: your backend, a SIEM, a GRC tool or a queue. You don't have to poll.

Register an endpoint

Dashboard → Admin → Integrations → Webhooks, or:

POST/api/v1/webhook-endpointsdashboard session
json
{ "url": "https://hooks.example.com/authentify", "description": "SIEM relay", "event_types": ["*"] }

The response includes the endpoint's signing secret (whsec_…). Sandbox and production have separate endpoints and secrets. URLs must be public https addresses (private and loopback addresses are refused), and each account can have up to 10 active endpoints.

CallPurpose
GET /api/v1/webhook-endpointsList endpoints with pending and failed counts.
GET /api/v1/webhook-endpoints/:idThe endpoint, its secret and its last 50 deliveries.
POST /api/v1/webhook-endpoints/:id/testSend a signed ping now and report the response.
DELETE /api/v1/webhook-endpoints/:idDisable it; queued deliveries are dropped.

What you receive

POST to your endpoint
Content-Type: application/json
Authentify-Event-Id: 6f1c...
Authentify-Event-Type: authorization_approval_granted
Authentify-Signature: t=1791388800,v1=5d41402abc4b2a76...

{
  "id": "6f1c...",
  "object": "event",
  "type": "authorization_approval_granted",
  "created_at": "2026-11-20T14:00:00.000Z",
  "data": {
    "audit_log_id": "6f1c...", "agent_id": "...", "action": "ISSUE_REFUND", "entity_id": "order-88231",
    "result": "AUTHORIZED", "reason": null, "authorization_request_id": "...",
    "approver_operator_id": "...", "detail": null,
    "seal": "...", "prev_seal": "...", "seal_version": 3,
    "created_at": "2026-11-20T14:00:00.000Z"
  }
}

type is the audit record's event type. To receive only some, list them in event_types. seal and prev_seal are the same values an evidence bundle verifies, so an event in your SIEM can later be matched to an offline-verified export.

Events you'll most likely want

Event typesWhen
authorization_authorized, authorization_deniedA request was decided without review.
authorization_approval_granted, authorization_approval_rejected, authorization_approval_expiredAn escalated request was decided by people, or ran out of time.
authorization_outcome_reportedSomeone reported what happened after a decision.
consent_granted, consent_declined, consent_paused, consent_resumed, consent_revokedA person you serve changed an agent’s access.
agent_revoked, account_kill_switch_activatedAn agent, or every agent, was stopped.
audit.checkpointThe daily signed checkpoint of your audit chain. Keep these.

data.detail says who and which consent:

json
"detail": {
  "end_user_id": "customer-42",
  "consent_id": "52e6bace-...",
  "identity_provider_id": null,
  "scope": ["READ_RECORDS", "SCHEDULE_APPOINTMENT"],
  "source": "consent_widget"
}

source is consent_widget (the consent screen), consent_manager (the person's connected-agents screen) or action_approval (they chose "Deny and pause" on a single-action approval). consent_id is absent on a decline.

Checkpoint events

json
{ "type": "audit.checkpoint", "data": {
  "checkpoint": "<JWT>", "timestamp_token": "<RFC 3161, base64>", "tsa_url": "https://freetsa.org/tsr",
  "head_seal": "9f2c...", "event_count": 1842, "last_event_id": "...", "last_event_at": "..." } }

See Checkpoints for how to check your log against one.

Verify the signature

Compute HMAC-SHA256 with the endpoint secret over "<t>.<raw body>" and compare it to v1. Use the raw request body, not re-serialized JSON, and reject timestamps more than five minutes old.

js
import crypto from 'crypto';

function verifyAuthentifyWebhook(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=', 2)));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(parts.v1 ?? '', 'hex');
  return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}

Delivery and retries

  • Events are queued in the same transaction that seals the record: a sealed record is always queued, and nothing unsealed is ever sent.
  • Delivery runs every few minutes. Any 2xx counts as delivered. Anything else (including redirects and timeouts after 10 seconds) is retried after 1 min, 5 min, 15 min, 1 h, 3 h, 6 h, 12 h, 24 h and 24 h, then marked failed.
  • Delivery is at least once and order isn't guaranteed. Deduplicate on Authentify-Event-Id; order by prev_seal or created_at.