Skip to content

Webhook event reference

AtmanID sends an HTTP POST to each webhook subscription whose event list includes the event. This page lists every event name a subscription can hold, says which of them AtmanID emits today and from where, and describes the delivery itself. For a walkthrough of a receiver, see webhook signature verification in Common patterns.

Event names are the published contract a subscriber matches on: they are added to, never renamed.

Where a subscription is created

Where Events offered
The Webhooks settings page in the app The admin catalogue: every event in the table below marked Admin
The Developer Portal in the app The admin catalogue
POST $ATMANID_BASE_URL/api/v1/webhooks with an API key Standard keys: the events marked Standard. Partner and internal keys: the events marked Partner. At most 32 events per subscription.

Every signing secret is whsec_ followed by 64 hexadecimal characters. A secret issued before 31 October 2026 by the Webhooks settings page, or by rotating any subscription’s secret, is 64 hexadecimal characters with no prefix, and keeps working until you rotate it. Do not check the prefix.

The secret is returned once, when the subscription is created or its secret is rotated, and is stored encrypted. Use the whole string, including the whsec_ prefix, as the HMAC key.

Rotating a secret switches X-Webhook-Signature to the new secret at once, and every attempt sent after the rotation, retries included, is signed with it. For an overlap window, 24 hours unless the rotation asks for 0 to 168, X-AtmanID-Signature also carries a signature made with the old secret. A receiver that verifies X-AtmanID-Signature can therefore switch to the new secret at any point in the window without rejecting a delivery.

The delivery

Every event delivery is a POST with a JSON body:

{
"id": "evt_3f9a1c0b7d2e4a51",
"event_type": "ACCESS_APPROVED",
"timestamp": "2026-10-30T14:02:11.482Z",
"tenant_id": "6f1d2c3b-0000-4000-8000-000000000001",
"api_version": "v1",
"data": { }
}
Field Meaning
id evt_ and 16 hexadecimal characters. One per event: every subscription that receives the event, and every retry, carries the same id. Deduplicate on it.
event_type The event name.
timestamp When AtmanID dispatched the event (ISO 8601, UTC).
tenant_id Your tenant.
api_version v1.
data The event’s fields, listed per event below.

Headers:

Header Value
Content-Type application/json
X-Webhook-Signature sha256= and the hex HMAC-SHA256 of the exact body bytes, keyed with the subscription’s secret
X-AtmanID-Signature t= and the Unix time the attempt was signed, then one v1= per secret: the hex HMAC-SHA256 of <t>.<body>. One v1 normally; two during a rotation’s overlap window, the new secret’s first. Added 31 October 2026.
X-Webhook-ID The subscription’s id
X-Delivery-ID The delivery’s id, the same on every retry and manual redelivery of it. unknown in the rare case AtmanID could not record the delivery.
X-Attempt-Number 1 for the first attempt, then 2 to 6
X-Event-Type The event name
X-AtmanID-API-Version v1

Any 2xx response counts as delivered. AtmanID waits up to 10 seconds and does not follow redirects: a 3xx counts as a failure. The URL must resolve only to public addresses; a URL that does not is not retried, and the subscription is suspended.

Verify the signature

Compute the HMAC over the raw body before you parse it. Parsing and re-serialising changes the bytes.

Node.js:

import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifyAtmanidWebhook(rawBody, signatureHeader, secret) {
if (!signatureHeader || !signatureHeader.startsWith('sha256=')) return false;
const received = Buffer.from(signatureHeader.slice('sha256='.length), 'hex');
const expected = createHmac('sha256', secret).update(rawBody).digest();
return received.length === expected.length && timingSafeEqual(received, expected);
}

Python:

import hashlib
import hmac
def verify_atmanid_webhook(raw_body: bytes, signature_header: str | None, secret: str) -> bool:
if not signature_header or not signature_header.startswith("sha256="):
return False
expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(signature_header[len("sha256="):], expected)

Reject the request with 401 when verification fails. Then look up id in a store of processed events and skip it if present; keep processed ids for at least a day, because retries span about ten and a half hours. Do not reject a delivery for an old timestamp: a retry legitimately arrives hours after the event.

The timestamped signature

X-AtmanID-Signature also signs the time of the attempt, so a receiver can refuse a captured delivery replayed later. It is signed afresh on every attempt, so its t is recent even when the event is hours old. Accept the delivery when t is within five minutes of your clock and any v1 matches:

import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifyAtmanidSignature(rawBody, header, secret, toleranceSeconds = 300) {
if (!header) return false;
const parts = header.split(',').map((p) => p.split('='));
const t = Number(parts.find(([k]) => k === 't')?.[1]);
if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
return parts.filter(([k]) => k === 'v1').some(([, v]) => {
const received = Buffer.from(v ?? '', 'hex');
return received.length === expected.length && timingSafeEqual(received, expected);
});
}

X-Webhook-Signature stays as it is; verifying either header is supported.

Retries and suspension

A failed attempt (a network error, a timeout, or a non-2xx response) is retried. A job runs every two minutes and sends each retry that is due, once: two runs never send the same attempt.

An attempt that never finished, for example because AtmanID stopped while sending it, counts as an attempt and is retried as the next one about 10 minutes later. Its delivery records attempt N did not complete. Your endpoint may have received that attempt, so the event can arrive twice; deduplicate on id. An unfinished attempt more than 12 hours old is abandoned instead of retried. A redelivery that never finished is marked failed, and a delivery cannot be redelivered while an attempt of it is being sent.

Attempt Sent
1 When the event happens
2 1 minute after attempt 1 failed (each wait below can be up to a fifth longer, never shorter)
3 5 minutes after attempt 2 failed
4 30 minutes after attempt 3 failed
5 2 hours after attempt 4 failed
6 8 hours after attempt 5 failed

After the sixth failure, or a sixth attempt that never finished, the delivery is abandoned. Every failed attempt is audited as WEBHOOK_DELIVERY_FAILED, every success as WEBHOOK_DISPATCHED.

A subscription is suspended after five failed attempts in a row, counted across all its deliveries. A successful delivery resets the count. A suspended subscription receives no new events, and its pending retries are abandoned when they come due. Turning the webhook back on in the app resumes it and resets the count. When a subscription is suspended, AtmanID emits WEBHOOK_SUBSCRIPTION_SUSPENDED to any other active subscription in the tenant that lists it.

A person can also redeliver one logged delivery from the app. That is a single attempt with the next attempt number; it is not retried and does not count toward suspension.

Test deliveries

POST /api/v1/webhooks/{id}/test, the Developer Portal and the Webhooks settings page each have a test button, and all three send the same delivery: the envelope above with event_type WEBHOOK_TEST, an id of evt_test_ and 16 hexadecimal characters, data { message, subscription_id }, and a top-level "test": true. It carries all of the headers above; X-Delivery-ID starts test_ and X-Attempt-Number is 1.

Test deliveries are signed like any other. They are not logged, retried or counted toward suspension.

Event catalogue

Offered says where a subscription can include the event: Admin (both pages in the app), Standard and Partner (the API key tiers on /api/v1/webhooks). Emitted today says what currently sends it.

An event marked not emitted is not offered in the app. POST and PATCH /api/v1/webhooks still accept it, for the key tiers listed, and name it in a warnings entry on the response (PATCH only for an event it adds): { "code": "EVENT_NOT_AVAILABLE", "message", "events": [ ... ] }. A tenant that turns enforcement on gets 400 EVENT_NOT_AVAILABLE instead, with details.events, and nothing is saved (API 1.33.0). Each event comes off this list in the release that starts sending it; the API changelog says when.

Identity lifecycle

Event Offered Emitted today data fields
USER_CREATED Admin, Standard, Partner A joiner through POST /api/v1/jml/joiner user_id, email, full_name, identity_type, is_rehire, identity_event_id, hris_system, source (api)
USER_DEPROVISIONED Admin, Standard, Partner A leaver through POST /api/v1/jml/leaver user_id, email, full_name, termination_date, offboarding_type, identity_event_id, hris_system, source (api)
JOINER_PROVISIONED Admin, Standard, Partner A joiner’s provisioning finishes (completed or partial) — the JML joiner run, or a manager approving a held joiner. A failed run sends nothing. user_id, email, identity_event_id, status (completed or partial), accounts_provisioned, tickets_created, re_joiner, source (joiner_workflow or manager_approval)
MOVER_UPDATED Admin, Standard, Partner A person’s department or title changes: the JML mover run, a lifecycle transfer, a bulk department update, a SCIM update, or an HR source sync. A change that leaves both as they were sends nothing. user_id, email, identity_event_id (null outside the mover run), previous_department, department, title, status, source (mover_workflow, transfer, bulk_update, scim, hr_sync)
LEAVER_DEPROVISIONED Admin, Standard, Partner A person leaves for good — moves into INACTIVE, DEPROVISIONED or TERMINATED from any other status — by any path: an admin termination, the JML leaver run, SCIM delete or a rescinded pre-hire, end of access after the grace period, vendor expiry or offboard, a bulk or CSV termination, or an HR source sync. Sent once per departure: whatever runs after it (a leaver run finishing the clean-up, a repeated delete) sends nothing. user_id, email, identity_event_id (null outside the leaver run and end of access), reason, status (completed, partial, or failed when a leaver run stopped after the person had left — finish it with Offboard now), source (admin_terminate, leaver_workflow, scim, end_of_access, vendor_expiry, vendor_offboard, bulk_terminate, csv_termination, hr_sync)
IDENTITY_SUSPENDED Admin, Partner A person’s access is stopped without them leaving: an admin suspension, SCIM active: false, a risk response that locks the account, an emergency lock, a vendor bulk suspend, or an HR source sync. Already suspended: nothing sent. Going on leave is not a suspension. user_id, email, status (SUSPENDED or LOCKED), previous_status, reason, source (admin, scim, risk_lock, emergency_lock, vendor_bulk, hr_sync)
IDENTITY_REACTIVATED Admin, Partner A person’s access is restored: an admin unsuspend or unlock, SCIM active: true or a SCIM rehire, a rejoin, extending an expired external’s end date, or an HR source sync. An unsuspend the identity provider still holds, a return from leave, or a start date arriving sends nothing. user_id, email, previous_status, reason, source (admin, scim, rejoin, access_extended, hr_sync)
CONTRACTOR_EXPIRING Admin, Partner A contractor, vendor or partner’s access ends within 30, 14 or 7 days — once per threshold for each end date (a new end date re-arms it) user_id, email, identity_type, expires_at, days_remaining, threshold_days
CONTRACTOR_EXPIRED Admin, Partner Their end date passes and access ends (reversible by extending it, until they are offboarded after the grace period) user_id, email, identity_type, expires_at

USER_CREATED and USER_DEPROVISIONED come only from the two /api/v1/jml endpoints; the events below them come from every path that makes the change, named in source. New source values may be added.

Access governance

Event Offered Emitted today data fields
ACCESS_REQUESTED Admin, Standard, Partner An access request is submitted. A multi-item request sends one event per item, with batch_id. request_id, ref_code, requester_id, requester_name, entitlement, application, risk_level, workflow, total_stages, and batch_id for an item of a multi-item request
ACCESS_APPROVED Admin, Standard, Partner The final approval stage approves a request, by a person or by auto-approval request_id, ref_code, requester_id, entitlement, application, decision (APPROVED), stage, total_stages; requested_role_id when the request was for a role; auto_approved: true when auto-approved
ACCESS_REVOKED Admin, Standard, Partner Two cases, told apart by their fields. (1) An approver rejects a request — deprecated: also sent as ACCESS_REQUEST_REJECTED since API 1.34.0, and no longer sent as ACCESS_REVOKED after 2027-06-01; subscribe to ACCESS_REQUEST_REJECTED. Until then a subscription to both receives two deliveries for one rejection (each with its own id); dedupe on data.request_id. (2) A revocation ticket is executed and at least one account was removed. (1) request_id, ref_code, requester_id, entitlement, application, decision (REJECTED), stage, total_stages. (2) ticket_id, mode, status, attempted, succeeded, failed, skipped_already_removed, completed, subject
ACCESS_REQUEST_REJECTED Admin, Standard, Partner An approver rejects a request, in the app, by bulk reject, from an approval email, through the assistant or POST /api/v1/access-requests/{id}/decision (since API 1.34.0). An administrator’s force-reject and a deadline policy’s auto-reject send no event yet. request_id, ref_code, requester_id, entitlement, application, decision (REJECTED), stage, total_stages
ACCESS_REQUEST_EXPIRED API only (Partner), with a warning Not emitted
ACCESS_REQUEST_ITEM_APPROVED Not offered on any create path An item of a multi-item request is finally approved request_id, parent_request_id, ref_code, entitlement, application, requester_id, stage, total_stages
ACCESS_REQUEST_ITEM_PROVISIONED Not offered on any create path Immediately after ACCESS_REQUEST_ITEM_APPROVED As ACCESS_REQUEST_ITEM_APPROVED, plus provisioned_at
ACCESS_REQUEST_ITEM_REJECTED Not offered on any create path An item of a multi-item request is rejected As ACCESS_REQUEST_ITEM_APPROVED
ENTITLEMENT_GRANTED API only (Partner), with a warning Not emitted
ENTITLEMENT_REVOKED_DIRECT API only (Partner), with a warning Not emitted

Risk and separation of duties

Event Offered Emitted today data fields
SOD_VIOLATION Admin, Standard, Partner An access request conflicts with an SoD rule. One event per conflicting rule. user_id, user_name, rule_name, severity (BLOCK or WARN), conflict_pair (the two entitlement names), context (access_request), pending (true when the other side is requested but not yet held)
SOD_VIOLATION_RESOLVED API only (Standard, Partner), with a warning Not emitted
RISK_SCORE_CHANGED API only (Partner), with a warning Not emitted
HIGH_RISK_AGENT_DETECTED API only (Partner), with a warning Not emitted

Certifications

Event Offered Emitted today
CERT_CAMPAIGN_STARTED API only (Partner), with a warning Not emitted
CERT_COMPLETED API only (Standard, Partner), with a warning Not emitted
CERT_AUTO_REVOKED API only (Partner), with a warning Not emitted
CERT_AUTO_CERTIFIED API only (Partner), with a warning Not emitted
CERT_ESCALATED API only (Partner), with a warning Not emitted

Certification outcomes are in the audit trail under the same names; they are not sent as webhooks yet.

Non-human identities and agents

Event Offered Emitted today data fields
DECOY_CREDENTIAL_USED Admin Someone presents a decoy credential decoy_id, label, placement, event_id, source_ip, user_agent (first 200 characters), method, path (first 200 characters). Never the credential or the request body.
AGENT_CRITICAL_ESCALATED Admin A critical agent detection has not been acknowledged within 5 minutes anomaly_id, agent_id, ack_window_minutes, itdr_mode, automatic_step, title
NHI_REGISTERED API only (Partner), with a warning Not emitted
NHI_SECRET_EXPIRING API only (Partner), with a warning Not emitted
AGENT_DELEGATION_CREATED API only (Partner), with a warning Not emitted
AGENT_DELEGATION_REVOKED API only (Partner), with a warning Not emitted

Audit integrity

Event Offered Emitted today data fields
AUDIT_CHAIN_BROKEN Admin, Partner The nightly check (02:30 UTC) finds a gap or tampering in recent entries, or the weekly full-history check (Sundays, 03:30 UTC) finds the chain not intact Nightly: status, verified, first_chain_seq, last_chain_seq, broken_at_seq, break_type, tenant_name, checked_at, trigger. Weekly: the same plus scope (full_history), complete, tamper_reason, historical_writer_bug_count, anchors_checked, anchor_problems
AUDIT_ANCHOR_INVALID Admin The nightly check finds a signed anchor that does not verify, or the weekly check finds an anchor mismatch Nightly: anchor_status, anchor_verify_reason, tenant_name, checked_at. Weekly: the weekly fields above
AUDIT_ANCHOR_R2_DIVERGENT Admin The nightly check finds the off-site copy of the anchors differs from the database r2_mirror_status, r2_divergence_reason, db_anchor_sequence, tenant_name, checked_at
AUDIT_CHAIN_VERIFIED API only (Partner), with a warning Not emitted. A clean check is recorded in the audit trail only.

A super admin can send a test of the three emitted audit-integrity events with POST /api/admin/audit-integrity-test-alert (a signed-in session, not an API key). Its data is { synthetic: true, test: true, note, condition, triggered_by, checked_at }, so a SIEM rule can ignore it.

Platform

Event Offered Emitted today data fields
WEBHOOK_SUBSCRIPTION_SUSPENDED Partner A subscription in the tenant is suspended after repeated failures subscription_id, url, failure_count, last_error, suspended_at
WEBHOOK_TEST Admin, Standard, Partner Only by a test button; see test deliveries
MFA_ENROLLED API only (Standard, Partner), with a warning Not emitted

© AtmanID · Privacy