> ## Documentation Index > Fetch the complete documentation index at: https://docs.domesystems.ai/llms.txt > Use this file to discover all available pages before exploring further. # Events > Audit v1 and webhook event contracts: envelopes, enums, catalogs, filters, and headers This page lists event types, shared envelope fields, and filter operators. Typed `payload` / `data` field schemas are defined per event type in the product API and dashboard catalog. For how the one trail works, see the [Audit events](/concepts/audit) concept. To query and reconstruct events, see [Audit events](/operate/audit). | Contract | Schema | Surfaces | | --------------------------------- | ----------------------------------- | ------------------------------------------- | | Audit v1 | Full envelope + typed `payload` | Query, stream, export, ingest | | Webhooks | `dome.webhook.v1` envelope + `data` | Signed HTTP delivery | | OpenTelemetry / product telemetry | Separate models | Observability only; not compliance evidence | ## Audit v1 Audit v1 is the durable workspace event trail. Every query, stream, export, and ingest record uses this envelope and type catalog. ### Envelope Every audit event uses this envelope. Envelope fields are filterable without inspecting `payload`. The shape is identical across CLI, MCP, SDK, dashboard, stream, query, and export. | Field | Type | Description | | ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------- | | `event_id` | UUID | Globally unique event identifier | | `event_type` | string | Concrete event (for example `mcp.tool_call.completed`) | | `event_class` | enum | `governing`, `state_change`, `security`, `audit_access` | | `result` | enum | `attempted`, `succeeded`, `denied`, `failed`, `filtered`, `noop`, `permitted` | | `occurred_at` | timestamp | When the event happened at the producer | | `accepted_at` | timestamp | When the audit pipeline durably accepted it | | `scope` | object | `organization_id`, `tenant_id`, `workspace_id`, `agent_id` | | `actor` | object | `kind`, `id`, `display`, `email`, plus [caller authentication context](#caller-authentication-context) | | `identity_chain` | object | Delegation hops; act-as hops carry [end-user attributes](#act-as-end-user-attributes) | | `primary_resource` | object | `kind` + `id` of the resource the event is about | | `related_resources` | object\[] | Additional resources referenced by the event | | `request_surface` | object | Origin surface and [network context](#network-and-transport-context); unset on many runtime authorization decisions | | `correlation` | object | `trace_id`, `activity_id`, `activity_trust`, `idempotency_key` — refer to [Correlation](#correlation) | | `operation_id` | UUID | Stable ID for a multi-event operation | | `parent_event_id` | UUID | The event that caused this one | | `payload` | object | Event-specific typed payload (`dome.audit.v1.V1`) | | `data_handling` | object | Flags: `omitted`, `summarized`, `truncated`, `redacted`, `hashed`, `encrypted` | The fields above are the complete customer envelope. Internal pipeline metadata is not returned. ### Enum rendering Enum fields (`event_class`, `result`, `actor.kind`, `scope.kind`, `primary_resource.kind`, `request_surface.surface`) render in one of two forms. Filters use the same form the surface returns. | Surface | Enum form | | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | CLI (table and `--format json`), MCP tool results, dashboard, exports (`json`, `jsonl`, `csv`, `ocsf`, `cef`) | Short tokens: `governing`, `denied`, `gateway_mcp`, `rule_bundle` | | gRPC / Connect API and generated SDK clients | Full constants: `EVENT_CLASS_GOVERNING`, `EVENT_RESULT_DENIED`, `INITIATOR_SURFACE_GATEWAY_MCP` | A short token is the constant with its type prefix stripped and lowercased. CLI flags and MCP arguments take short tokens. API request fields take full constants or their integer values. ### Network and transport context Configuration events carry network origin under `request_surface`. | Field | Type | Description | | ----------------- | ------ | ------------------------------------------------------------------------------------- | | `source_ip` | string | Caller IP from the inbound connection, resolved through the trusted-hops boundary | | `user_agent` | string | Raw `User-Agent` header, capped at 512 bytes (`data_handling.truncated` when clipped) | | `http_method` | string | HTTP verb (`GET`, `POST`, …) for HTTP-surfaced requests | | `source_ip_class` | string | Derived zone: `private`, `vpc`, `public`, `unknown` | OCSF exports map `source_ip` to `src_endpoint.ip`; `user_agent` and `http_method` are carried under `unmapped`. CEF exports map them to `src`, `requestClientApplication`, and `requestMethod`. `source_ip` is the **rightmost trusted** entry of `X-Forwarded-For + [connecting peer]`. `DOME_TRUSTED_HOPS` on the api-server and gateway is the number of appending reverse-proxy hops in front of Dome. | `DOME_TRUSTED_HOPS` | Topology | Trusted entry | | ------------------- | ---------------------------------------- | ----------------------------- | | `0` | Dome exposed directly to clients | Connecting peer (XFF ignored) | | `1` *(default)* | Single fronting ALB in XFF `append` mode | Entry the ALB appended | | `2` | `CDN → ALB → Dome` | Entry the inner hop appended | | `N` | N appending hops | Nth from the right | Set `DOME_TRUSTED_HOPS` to match your actual edge. Over-trusting lets a caller forge `source_ip` by injecting headers; under-trusting records the proxy IP instead of the client. Spoofed values reach audit events, OCSF/CEF exports, the dashboard Authority card, and the credential-provision rate-limiter key. The resolver clamps to the leftmost entry when fewer hops are present — it never reads past the boundary. The default `1` assumes one AWS ALB in XFF `append` mode. The ALB appends the connecting client on the right without stripping a caller-supplied `X-Forwarded-For`, so the rightmost entry is the only edge-guaranteed value. ### Caller authentication context `actor` includes how the immediate principal authenticated. | Field | Type | Description | | -------------------- | ------ | ------------------------------------------------------------------------------------ | | `auth_method` | string | `session`, `api_key`, `agent`, `gateway`, `admin_token` | | `session_id` | string | Browser session ID when session-backed | | `api_key_id` | string | Platform or agent API key ID when key-backed | | `api_key_scope_kind` | string | `workspace`, `tenant`, `org`, or `platform` | | `api_key_scope_id` | string | ID of the key's scope | | `assurance_level` | string | Authentication assurance level (for example `aal1`, `aal2`) when surfaced by the IdP | ### Act-as end-user attributes When an agent acts on behalf of an end user, the corresponding `identity_chain` hop carries these fields. Producers cap each list at 32 entries. | Field | Type | Description | | --------------------- | --------------------- | ------------------------------------- | | `roles` | string\[] | End-user roles supplied by the caller | | `groups` | string\[] | End-user groups | | `claims` | `map` | Additional verified claims | | `verification_method` | string | `oidc`, `hmac`, or `none` | ### Correlation | Field | Scope | | ------------------------- | ------------------------------------------------------------ | | `operation_id` | One action phase pair (`attempted` → `succeeded` / `denied`) | | `correlation.trace_id` | One HTTP request cascade | | `correlation.activity_id` | One session, LLM turn, or scripted run across planes | An activity chain is the set of audit events that share one `activity_id` within a workspace. Chains are computed at read time; there is no stored chain object. | `correlation.activity_trust` | Meaning | | ---------------------------- | -------------------------------------------------- | | `server_owned` | Dome set the id. A caller cannot forge this label. | | `caller_asserted` | The id arrived on the `X-Dome-Activity-Id` header. | | `unspecified` | No `activity_id` on this event. | `activity_id` can be set by a CLI run (`--activity` or `DOME_ACTIVITY_ID`), an SDK session, an agent request header, or Dome for browser and assistant threads. Chain reads return only the active workspace's slice, so human-meaningful IDs (`case-12345`) are safe to use. `activity_trust` is provenance metadata, not a grouping key. ### Event classes | Class | Description | | -------------- | ----------------------------------- | | `governing` | Authorization and runtime decisions | | `state_change` | Configuration mutations | | `security` | Authentication front door | | `audit_access` | Reads of the trail itself | ### Event types Types by `event_class`. #### `governing` | Type | Description | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `authorization.decision` | Cedar evaluation produced an allow or deny | | `authorization.act_as.rejected` | Caller cannot impersonate the requested subject | | `authorization.staleness_rejected` | Effective policy too stale to authorize | | `mcp.tool_call.attempted` | Tool call arrived at the gateway | | `mcp.tool_call.completed` | Tool call resolved; `result` is `succeeded`, `failed`, or `denied` | | `mcp.tool_result.filtered` | Tool result fields redacted before return | | `mcp.tools_list.completed` | Agent listed available tools | | `llm.model_call.attempted` | LLM dispatch arrived at the gateway | | `llm.model_call.completed` | LLM dispatch resolved; carries token usage and cost | | `llm.model_stream.started` | First chunk of a streaming response reached the caller | | `llm.model_call.failover` | A candidate failed and the router moved to the next one | | `llm.model_request.filtered` | Filter changed the request before it left the gateway | | `llm.model_result.filtered` | LLM output fields redacted before return | | `llm.models_list.completed` | Agent listed available models | | `assistant.message.attempted` | Assistant message governing event | | `assistant.message.stream.started` | Assistant stream governing event | | `access.denied` | Ingress deny (unauthenticated, wrong caller type, Cedar deny, kill switch, tenant mismatch, exhausted Quota, or no pool/connection matched) | | `credential.required` | Tool call denied; per-user credential missing | Every `llm.model_*` event carries `provider` — the vendor identity from the connection. Filter on `provider` to attribute spend, latency, or denial rate per vendor. Denials on the LLM path may carry `data.reason`: | `data.reason` | Meaning | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `pool_unknown` | No pool, connection, or `match_when` predicate matched, and the workspace has no default pool. Returned as HTTP `404`. | | `platform_kill_switch` | The platform-wide LLM kill switch is active. | | `workspace_kill_switch` | The workspace's LLM kill switch is active. | | `tenant_mismatch` | The workspace's owning tenant did not match the caller's session tenant. | | `permission_denied` | Cedar denied the call. Failover candidate skips may also carry `data.detail = "cedar_deny"`. | Reasons are short, snake\_case, and stable. Treat unknown values as a generic deny. Runtime handling is on [Develop](/develop#errors-and-denials). Ingress behavior is on the [LLM gateway](/concepts/gateways/llm-gateway) concept. #### `state_change` | Type | Description | | ------------------------------------------- | ----------------------------------------------------------------------------------------- | | `agent.registered` | Agent created | | `agent.activated` | Agent became active | | `agent.updated` | Agent record updated | | `agent.suspended` | Agent suspended | | `agent.reactivated` | Agent reactivated | | `agent.revoked` | Agent revoked | | `agent.deleted` | Agent deleted | | `agent.api_key.created` | Agent API key created | | `agent.api_key.revoked` | Agent API key revoked | | `agent.api_key.rotated` | Agent API key rotated | | `workspace.created` | Workspace created | | `workspace.deleted` | Workspace deleted | | `workspace.config.changed` | Workspace config write. Payload carries `previous_value` and `new_value` per changed path | | `workspace.role.assigned` | Workspace role assigned | | `workspace.role.removed` | Workspace role removed | | `tenant.created` | Tenant created | | `tenant.deleted` | Tenant deleted | | `tenant.role.assigned` | Tenant role assigned | | `tenant.role.removed` | Tenant role removed | | `organization.created` | Organization created | | `organization.updated` | Organization updated | | `organization.deleted` | Organization deleted | | `organization.domain.added` | Organization domain added | | `organization.domain.verified` | Organization domain verified | | `organization.membership.set` | Organization membership set | | `authorization.rule_bundle.deployed` | Rule bundle deployed | | `authorization.rule_bundle.rolled_back` | Rule bundle rolled back | | `authorization.rule_bundle.deploy_failed` | Rule bundle deploy failed | | `authorization.rule_bundle.validated` | Rule bundle validated | | `authorization.rule_bundle.deleted` | Rule bundle deleted | | `authorization.policy_snapshot.applied` | Policy snapshot applied | | `gateway.connection.created` | Gateway connection created | | `gateway.connection.updated` | Gateway connection updated | | `gateway.connection.deleted` | Gateway connection deleted | | `gateway.connection.credential.rotated` | Connection credential rotated | | `gateway.connection.classification.updated` | Field classifications updated | | `llm.pool.created` | LLM pool created | | `llm.pool.updated` | LLM pool updated | | `llm.pool.deleted` | LLM pool deleted | | `llm.pool.default_set` | Default LLM pool set | | `llm.pool.member.added` | LLM pool member added | | `llm.pool.member.removed` | LLM pool member removed | | `mcp.tool.status_changed` | MCP tool status changed | | `mcp.tool_catalog.sync.completed` | MCP tool catalog sync completed | | `mcp.tool_catalog.observed` | MCP tool catalog observed | | `credential.link.issued` | Credential link issued | | `credential.link.consumed` | Credential link consumed | | `credential.oauth.consent_granted` | OAuth consent granted | | `credential.oauth.disconnected` | OAuth disconnected | | `scheduler.job.created` | Scheduler job created | | `scheduler.job.updated` | Scheduler job updated | | `scheduler.job.deleted` | Scheduler job deleted | | `scheduler.job.run.completed` | Scheduler job run completed | | `scheduler.job.run.failed` | Scheduler job run failed | | `platform.api_key.created` | Platform API key created | | `platform.api_key.revoked` | Platform API key revoked | | `integration.instance.deleted` | Integration instance deleted | | `integration.catalog.deleted` | Integration catalog entry deleted | #### `security` | Type | Description | | ----------------------------------- | ---------------------------------------------------------- | | `identity.login.completed` | Platform user finished IdP login | | `identity.login.failed` | IdP login rejected | | `identity.session.terminated` | Session ended (logout, forced revocation, expiry) | | `identity.impersonation.started` | Operator began impersonating another user | | `identity.impersonation.terminated` | Impersonation ended | | `agent.token.issued` | Agent exchanged an API key for a short-lived token | | `agent.token.rejected` | Token exchange denied | | `platform.user.created` | First-time platform user provisioning on initial IdP login | | `credential.link.rejected` | Credential-link consume rejected before state change | | `credential.oauth.consent_rejected` | OAuth consent callback rejected before state change | Not in the audit catalog: `identity.session.created`, `identity.session.switched`, and `identity.session.rotated` (operational telemetry only — session rotation is a background \~5-minute token refresh). Login, token issuance, and impersonation start fail closed until their audit event is durable. Forced terminations complete first and audit with retry so an unavailable audit store cannot prevent revocation. #### `audit_access` | Type | Description | | ------------------------------------- | ----------------------------------- | | `audit.query.completed` | `QueryEvents` | | `audit.event.read` | `GetEvent` | | `audit.stream.opened` | `StreamEvents` opened | | `audit.stream.closed` | `StreamEvents` closed | | `audit.export.requested` | Export requested | | `audit.export.completed` | Export completed | | `simulation.result.read` | Simulation result read | | `assistant.tool.simulated` | Assistant tool simulation | | `assistant.tool.validated` | Assistant tool validation | | `gateway.policy_simulation.completed` | Gateway policy simulation completed | ### Decision provenance These types stamp policy snapshot fields into `payload` when a bundle was loaded: `authorization.decision`, `mcp.tool_call.completed`, `mcp.tool_call.attempted`, `llm.model_call.completed`, `mcp.tool_result.filtered`, `llm.model_result.filtered`. | Field | Type | Description | | ------------------------------ | --------- | ---------------------------------------------------------------------------------------------------- | | `payload.bundle_etag` | string | Content hash of the effective policy at decision time | | `payload.contributing_bundles` | object\[] | Bundles merged into the effective policy (`bundle_id`, `name`, `scope_kind`, `scope_id`, `sequence`) | | `payload.rule_id` | string | File identifier of the matched rule | Events with no loaded bundle omit these fields. The dashboard decision explainer deep-links contributing bundles to `/rules/bundles?scope=&scopeId=`; the same fields are available on `dome audit get`, `dome_audit_get_event`, and `QueryEvents`. ### Payload filters Payload filters match fields inside the event-specific payload (for example `mcp.tool_call.completed.tool`). Each filter is scoped to one `event_type` and one `field`. Non-filterable fields return a validation error. | Operator | Behavior | | -------- | ----------------------------------------------------------------------------------- | | `equals` | Default when a value is provided. Payload field matches any of the supplied values. | | `exists` | Payload field is present and non-empty. | Stream and query share this vocabulary. ### Ingest | Path | Description | | -------------------------------- | ----------------------------- | | `POST /api/v1/audit/events` | Gateway batch upload to Dome | | Connect RPC `Audit/IngestEvents` | Programmatic ingestion (SDKs) | Delivery semantics: at-least-once. ## Webhooks Webhooks deliver a signed public projection of selected events for automation. The wire shape and type catalog differ from Audit v1 even when type strings overlap. Operating limits and retry status handling are on [Webhooks](/concepts/audit/webhooks#operating-limits). ### Envelope ```json theme={"system"} { "schema": "dome.webhook.v1", "event_id": "0b9c1e2a-6f4d-4c3b-9a1e-2f5d7c8b0a11", "event_type": "agent.suspended", "event_version": 1, "occurred_at": "2026-07-14T10:30:00.000Z", "scope": { "kind": "workspace", "tenant_id": "…", "workspace_id": "…" }, "actor": { "kind": "platform_user", "id": "…" }, "resource": { "type": "agent", "id": "…" }, "correlation": { "trace_id": "0af7651916cd43dd8448eb211c80319c", "operation_id": "…" }, "data": { "agent_id": "…", "status": "suspended", "agent_name": "checkout-worker", "reason": "policy_violation" } } ``` | Field | Description | | --------------- | ---------------------------------------------------------------- | | `schema` | Always `dome.webhook.v1` | | `event_id` | Delivery source event ID (random UUID; order by `occurred_at`) | | `event_type` | Webhook catalog type | | `event_version` | Public contract version for `data` | | `occurred_at` | Event time | | `scope` | Scope object | | `actor` | `kind` + `id` only (no email or display name) | | `resource` | `type` + `id` | | `correlation` | Correlation object | | `data` | Typed public payload (no PII, credentials, or raw tool payloads) | ### Delivery headers | Header | Description | | ---------------------- | ----------------------------------------------------------------------------------------- | | `webhook-id` | Unique ID of this delivery. Stable across retry attempts; a replay gets a fresh one. | | `webhook-timestamp` | Unix seconds when the body was signed. | | `webhook-signature` | Space-delimited `v1,` tokens over `..`. | | `Dome-Event-Id` | Source event ID; dedupe key (stable across retries and replays). | | `Dome-Event-Type` | Event type. | | `Dome-Event-Version` | Contract version of the payload. | | `Dome-Subscription-Id` | Subscription that produced the delivery. | | `Dome-Attempt` | 1-based attempt counter. | ### Bundles Subscriptions accept any combination of the catalog types. Bundles are presets: | Bundle | Count | Types | | ------------------ | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | Agent lifecycle | 8 | `agent.registered`, `agent.updated`, `agent.enrolled`, `agent.activated`, `agent.suspended`, `agent.reactivated`, `agent.revoked`, `agent.deleted` | | Governance changes | 24 | Rule bundle, workspace config and roles, gateway connections, Gateway membership, MCP tool status, verification providers | | Security signals | 8 | `access.denied`, `llm.output.filtered`, `mcp.tool_result.filtered`, `platform.api_key.{created,revoked}`, `agent.api_key.{created,rotated,revoked}` | | Incidents | 4 | `access.denied`, `agent.suspended`, `agent.revoked`, `audit.export.failed` | ### Event types #### Identity and access `platform.api_key.created`, `platform.api_key.revoked`, `agent.api_key.created`, `agent.api_key.rotated`, `agent.api_key.revoked`, `workspace.role.assigned`, `workspace.role.removed`, `verification.provider.created`, `verification.provider.updated`, `verification.provider.deleted` #### Agent lifecycle `agent.registered`, `agent.updated`, `agent.activated`, `agent.suspended`, `agent.reactivated`, `agent.revoked`, `agent.deleted`, `agent.enrolled` #### Policy and configuration `workspace.config.changed`, `workspace.freshness_window.updated`, `authorization.rule_bundle.deployed`, `authorization.rule_bundle.rolled_back`, `authorization.rule_bundle.deleted` #### Gateway and connections `gateway.connection.created`, `gateway.connection.updated`, `gateway.connection.deleted`, `mcp.tool_catalog.sync.completed`, `mcp.tool.status_changed`, `gateway.created`, `gateway.updated`, `gateway.deleted`, `gateway.tool_member.added`, `gateway.tool_member.removed`, `gateway.tool_source_member.added`, `gateway.tool_source_member.removed`, `gateway.llm_pool_member.added`, `gateway.llm_pool_member.removed`, `gateway.llm_model_member.added`, `gateway.llm_model_member.removed` #### Security decisions `mcp.tool_call.completed`, `mcp.tool_result.filtered`, `llm.output.filtered`, `access.denied` These fire per governed request. Point them at a log sink rather than a chat channel, and narrow with [subscription filters](/operate/webhooks#filters). #### Audit exports `audit.export.completed`, `audit.export.failed` #### Webhooks administration `eventing.test`, `eventing.destination.created`, `eventing.destination.updated`, `eventing.destination.deleted`, `eventing.subscription.created`, `eventing.subscription.updated`, `eventing.subscription.disabled`, `eventing.subscription.deleted` ### Audit v1 name map | Webhook `event_type` | Audit v1 `event_type` | | --------------------- | --------------------------- | | `llm.output.filtered` | `llm.model_result.filtered` | Where names diverge, the webhook wire name is authoritative for webhook deliveries. ## Next steps Use the catalogs from Operate and Manage: | Page | Contents | | ---------------------------------------- | --------------------------------------------- | | [Audit events](/concepts/audit) | How the one trail works | | [Webhooks](/concepts/audit/webhooks) | Signed public delivery model, limits, retries | | [Audit events](/operate/audit) | Query, get, activity chains | | [Stream Live Events](/operate/observe) | Stream Audit v1. OpenTelemetry | | [Subscribe to Events](/operate/webhooks) | Destinations, subscriptions, retries | | [Export Data](/manage/export) | Forwarders and ingest |