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 hashlibimport 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 |
Related
- Common patterns walks through a receiver.
- The API reference documents
/api/v1/webhooks(create, update, delete, test). - Audit event reference covers the events in the audit trail, which is broader than the webhook catalogue.
© AtmanID · Privacy