15. Event Reference¶
Every business event the platform emits, in one place. Two delivery mechanisms carry these events:
- Audit log — recorded for every event when
audit_enabled(default on). Common fields and theaudit_logschema are in §13.5; query API in §12.2. - Webhooks — delivered conditionally (only if a tenant endpoint subscribes). Envelope and delivery in §11.
Audit name (snake_case) and webhook name (dotted) are the same event in two delivery formats (e.g. user_created / user.created); — in the Webhook column means audit-only.
15.1 Event Catalog¶
Auth & Session (audit-only)
| Audit event | Webhook | Trigger | Metadata |
|---|---|---|---|
otp_sent |
— | OTP requested | mobile (hashed) |
login_attempt |
— | Auth attempt | method, reason (if failed) |
token_issued |
— | Token generated | grant_type |
token_refresh_failed |
— | Refresh token rejected | reason (invalid/expired/user_inactive) |
client_auth_failed |
— | Client credentials auth rejected | client_id, reason |
Users
| Audit event | Webhook | Trigger | Metadata / Data fields |
|---|---|---|---|
user_created |
user.created |
New user registered | method (otp/password/social/api) |
user_suspended |
user.suspended |
User suspended by admin | reason |
user_reactivated |
user.reactivated |
User reactivated by admin | reason |
user_deleted |
user.deleted |
DSR deletion | method, data_deleted |
identity_linked |
user.identity_linked |
Auth identity linked to existing user (account auto-linking, §5.11) | identity_type |
data_export |
— | DSR export | requester |
KYC — [POST-MVP] (§6)
| Audit event | Webhook | Trigger | Metadata / Data fields |
|---|---|---|---|
kyc_initiated |
kyc.initiated |
KYC verification session started | provider, level, session_id |
kyc_verified |
kyc.verified |
KYC completed successfully | provider, level, verified_data |
kyc_failed |
kyc.failed |
KYC verification failed | provider, reason |
Consent
| Audit event | Webhook | Trigger | Metadata / Data fields |
|---|---|---|---|
consent_granted |
consent.granted |
Consent recorded | consent_type, version, purposes |
consent_withdrawn |
consent.withdrawn |
Consent revoked | consent_id, reason |
Palm & Biometric
| Audit event | Webhook | Trigger | Metadata / Data fields |
|---|---|---|---|
palm_enrolled |
enrollment.complete |
Palm registered (at any device) | palm_id, type, device_id (webhook: user_id, palm_type, metadata) |
palm_enrollment_failed |
— | Enrollment rejected by vendor | reason (duplicate_biometrics, already_enrolled_for_type, license_capacity, etc.) |
palm_duplicate_detected |
— | Pre-enrollment similarity match found (§7.9) | enrolling_user_id, matched_user_ids, scores, severity: high |
palm_restriction_set |
— | Admin set query_type for user (§7.8) | user_id, query_type, set_by |
palm_thresholds_updated |
— | Admin tuned vendor thresholds (§7.14.2) | updated_by, old_thresholds, new_thresholds |
palm_vendor_unhealthy |
— | Vendor health check failed (§7.14.1) | reason, severity |
palm_vendor_unauthorized |
— | Vendor returned auth error | severity: critical |
palm_vendor_version_change |
— | Vendor version changed since last check | old, new |
palm_model_changed |
— | Active palm model switched, e.g. small→large (§7.10–8.14) | platform_admin_id, old_model, new_model |
palm_model_migration_started |
— | Admin triggered small→large migration (§7.11) | platform_admin_id, from_model, to_model |
palm_model_migration_completed |
— | Migration reprocessing finished and model switched (§7.11) | platform_admin_id, duration_s, reprocessed_count |
palm_model_migration_failed |
— | Migration aborted/failed; model unchanged (§7.11, high-severity) | platform_admin_id, reason |
Verification & Identification
| Audit event | Webhook | Trigger | Metadata / Data fields |
|---|---|---|---|
identification |
identification.complete |
1:N search. Webhook is audit/back-office only, never the device decision path (which is synchronous — §9) | status, scores (large model only), latency_ms, source (platform|device_reported) |
verification_complete |
verification.complete |
1:1 match succeeded | challenge_id, scores (large model only), source (audit); user_id, challenge_id, confidence, metadata (webhook) |
verification_failed |
verification.failed |
1:1 match failed (max attempts or expired) | challenge_id, attempt, reason |
(logged as device_transaction, §13.4 / §10.3) |
device.transaction.completed |
Device-initiated transaction resolved (§9) | user_id, device_id, product_key, action, decision, product_reference, metadata |
linked_service_created |
linked_service.created |
Tenant Admin registered a linked service (§9.2) | tenant_id, product_key, actor |
linked_service_unhealthy |
linked_service.unhealthy |
Linked service failed its health probe N consecutive times (§9.7) | tenant_id, product_key, reason, consecutive_failures, severity |
Devices & Certificates (audit-only)
| Audit event | Webhook | Trigger | Metadata |
|---|---|---|---|
device_created |
— | Device registered | device_id |
device_paired |
— | Scanner paired | device_id |
cert_renewed |
— | Device certificate renewed | device_id, old_fingerprint, new_fingerprint |
cert_renewal_failed |
— | Certificate renewal rejected | device_id, reason |
device_revoked |
— | Scanner revoked by admin | device_id, revoked_by |
device_certs_bulk_revoked |
— | Platform Admin invalidates many device certs at once — regenerating the platform CA (deployment-wide, §8.2.2) or a tenant-scoped forced rotation (§8.2) (high-severity) | platform_admin_id, scope (deployment/tenant), tenant_id (if tenant-scoped), affected_device_count |
Platform SSL / Certificates
| Audit event | Webhook | Trigger | Metadata / Data fields |
|---|---|---|---|
server_cert_uploaded |
— | Admin uploaded a new server TLS cert (§8.2.2) | platform_admin_id, fingerprint, expires_at, old_fingerprint |
server_cert_deleted |
— | Admin removed the server TLS cert; backend reverts to plain HTTP on next restart (rare; §8.2.2) | platform_admin_id, fingerprint |
cert_expiry_alert_sent |
platform.server_cert.expiring / .expired, platform.platform_ca.expiring / .expired |
Background job sent a cert-expiry alert at a threshold (§8.2.2). Platform-scoped webhooks (scope='platform', §11.6). |
audit: kind (server_cert/platform_ca), channel (ui/email/webhook), threshold_days, fingerprint, recipient_count. webhook: kind, fingerprint, expires_at, days_remaining, threshold_days (server cert thresholds 30/14/7/1/0; CA 60/30/14/7/1/0) |
platform_ca_generated |
— | Admin generated or uploaded a new platform CA (§8.2.2) | platform_admin_id, fingerprint, expires_at |
platform_ca_regenerated |
— | Admin regenerated the platform CA — destructive, invalidates all device certs (§8.2.2, high-severity) | platform_admin_id, old_fingerprint, new_fingerprint |
device_policy_changed |
— | Admin updated the device cert validity / renewal-window policy (§8.2.2) | platform_admin_id, old_policy, new_policy |
Console, Tenant & Client (audit-only)
| Audit event | Webhook | Trigger | Metadata |
|---|---|---|---|
platform_admin_added |
— | A new platform-admin role was granted to a console user (high-severity) | granted_by, granted_to, role |
tenant_deleted |
— | Tenant deactivation grace period elapsed and tenant data was hard-deleted (high-severity) | platform_admin_id, tenant_id, deletion_method |
challenge_created |
— | Verification challenge created | challenge_id, user_id, device_id, context |
client.created |
— | OAuth client created | client_id, name |
client.secret_regenerated |
— | Client secret rotated | client_id |
client.revoked |
— | OAuth client revoked | client_id |