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:
/api/v1/webhook-endpointsdashboard session{ "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.
| Call | Purpose |
|---|---|
GET /api/v1/webhook-endpoints | List endpoints with pending and failed counts. |
GET /api/v1/webhook-endpoints/:id | The endpoint, its secret and its last 50 deliveries. |
POST /api/v1/webhook-endpoints/:id/test | Send a signed ping now and report the response. |
DELETE /api/v1/webhook-endpoints/:id | Disable it; queued deliveries are dropped. |
What you receive
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 types | When |
|---|---|
authorization_authorized, authorization_denied | A request was decided without review. |
authorization_approval_granted, authorization_approval_rejected, authorization_approval_expired | An escalated request was decided by people, or ran out of time. |
authorization_outcome_reported | Someone reported what happened after a decision. |
consent_granted, consent_declined, consent_paused, consent_resumed, consent_revoked | A person you serve changed an agent’s access. |
agent_revoked, account_kill_switch_activated | An agent, or every agent, was stopped. |
audit.checkpoint | The daily signed checkpoint of your audit chain. Keep these. |
Consent events
data.detail says who and which consent:
"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
{ "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.
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
2xxcounts 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 byprev_sealorcreated_at.