Send audit events to an external system

Choose which governance audit events the VP Audit Log keeps, deliver them to a SIEM, webhook, stream, email, or Slack through an endpoint and an event set of audit events, set delivery limits, and confirm records arrive.

This guide selects the audit events the VP Audit Log keeps and adds an integration that delivers selected audit events to your own system, such as a security information and event management (SIEM) platform. For how audit events are selected and delivered, see Audit log.

No audit events are selected by default, so neither the Audit page nor any integration receives governance records until you choose them. Your compliance and security teams then have no durable, external record of what the gateway allowed, refused, or delegated.

Use this guide when:

  • Your SIEM, data lake, or alerting pipeline needs policy decisions, refused requests, or credential delegation records from the gateway.
  • You need a durable copy of audit records outside the appliance.
  • The Audit page shows no records, or fewer kinds of record than you expect.

This guide covers governance audit records. Lifecycle notifications, such as a user being approved or a gateway being disabled, use the same endpoints with their own event sets. For those, follow Set up event notifications instead.

Prerequisites

  • Dashboard access with the Administrator role. Only administrators can open Settings › Security and add or change integrations.
  • A destination ready to receive records: an HTTPS endpoint for a webhook, or a Kafka, Kinesis, Pulsar, or Redis Streams topic for a stream, with its connection details. Email and Slack also work, but send one message per record.
  • Approval to send the data. Audit records leave the appliance with the caller’s email and name, request details, and the signed Verifiable Presentation (VP).
  • A surface that requires an API key and has a Policy element that denies keyless requests, so a keyless test request generates audit records. Restrict surface access with API key authentication sets one up.

Steps

Choose the events the VP Audit Log keeps

  1. In the dashboard sidebar, select Settings, then open the Security tab.
  2. In the VP Audit card, turn on Enable VP Auditing. The Events to keep list appears, grouped by area.
  3. Select the events to keep on the Audit page. For this guide, select the Policies and Auth group checkboxes, which select Policy Decision and Authentication Failed. Add any other events your compliance requirements call for.
  4. Select Save.

The Audit events table describes every event in the list.

Add the endpoint for your destination

  1. In the dashboard sidebar, select Integrations, open the Endpoints tab, and select Add Endpoint.
  2. Enter a Name, and from Type select Webhook or Stream (Kafka, Kinesis, Pulsar, Redis). These suit audit volumes best, because every record is one delivery.
  3. Fill in the Configuration fields, such as URL and Signing secret for a webhook, or Platform, Topic or stream, and its connection details for a stream. The Endpoints reference lists every field.
  4. Select Save.

To reuse an endpoint you already have, skip this step.

Add an event set of the audit events to send

  1. In the dashboard sidebar, select Audit, then select Forward records beside the Audit Log heading. A new event set opens, named Governance Audit, with every audit event selected.
  2. Under Events, keep the events to send and clear the rest. For this guide, keep Policy Decision under Governance Audit: Policies and Authentication Failed under Governance Audit: Auth.
  3. Select Save.

When integrations already receive audit records, the Audit page button reads Forwarding to N integrations instead. Then open the Event Sets tab on the Integrations page, select Add Event Set, and select the events under the Governance Audit groups.

This selection is independent of Events to keep in Step 1, so the integration receives its events whatever the VP Audit Log keeps.

Add the integration

  1. On the Integrations page, open the Integrations tab and select Add Integration.
  2. Enter a Name, and select the endpoint from Step 2 under Endpoint and the event set from Step 3 under Event set.
  3. Leave the Payload field in the Template card empty. The default payload carries the event type, timestamp, appliance ID, and, under data, the full audit record as a JSON object, including its event_id and trace_id.

The Governance Audit delivery card appears, because the event set holds audit events.

Set the delivery limits

Under Delivery limits in the Governance Audit delivery card, set when the integration stops retrying a record:

  • Give up on a record after: the number of failed attempts after which the integration skips a record so the records behind it are delivered. Leave it empty to retry each record until it is delivered. While the destination is down, records are also skipped once they reach this limit. With the retry backoff, 10 attempts span about 8.5 minutes and 20 about an hour.
  • Skip records older than: an age in seconds after which records are skipped for this integration instead of delivered. Leave it empty to deliver records of any age.

Each value is a whole number of 1 or more. Leave both empty when your destination must receive every record.

Save the integration

Select Save.

Confirm

Replace <ENTRY_POINT_URL> with the Entry point URL of the API key surface from the prerequisites, shown at the top of its Access Point panel. The selected events and the integration take effect on the running gateway.

Test 1: keyless request returns 403

curl -k -X POST "<ENTRY_POINT_URL>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "message/send",
    "id": "audit-test-001",
    "params": {
      "message": {
        "role": "user",
        "messageId": "audit-msg-001",
        "parts": [{ "kind": "text", "text": "Hello" }]
      }
    }
  }'

The -k flag disables TLS certificate verification. Use this for local testing only; remove it in production.

Expected response: 403 Forbidden. The request produces an Authentication Failed record and a denied Policy Decision record for the same trace ID.

Test 2: Audit page lists the denied policy decision

Open Audit in the dashboard sidebar. Expected: the Audit Log list shows a new policy decision entry marked Deny for the surface. The Authentication Failed record for the same request appears under All.

Test 3: destination receives records with an event_id

Check your webhook endpoint or stream topic. Expected: two new records whose event_type is audit.auth_failed and audit.policy_decision. Each one’s data object carries an event_id and the same trace_id.

Delivery is at least once, so a record can arrive again, for example after a gateway restart. Deduplicate on event_id in your receiver.

Test 4: Audit page shows forwarding to the integration

On the Audit page, the button beside the Audit Log heading reads Forwarding to 1 integration, or a higher count if other active integrations deliver audit events. Selecting it opens the Integrations page.

Troubleshooting

SymptomLikely causeFix
Forward records or Add Integration is missing.Your account isn’t an administrator.Sign in as an administrator, or ask one to create the integration.
The destination receives nothing.The integration or its endpoint is disabled, or its event set holds no audit events.Turn on Active on the integration and its endpoint, check the event set’s events, and select Save.
The Forwarding to button shows a warning icon.At least one integration with audit events is disabled, or its endpoint is, and receives nothing.Hover over the button to see how many, then turn on Active on each of those integrations and endpoints, or delete the integrations.
The destination receives records, but the Audit page shows none.Enable VP Auditing is off, or the events are not selected under Events to keep.In Settings › Security, turn on Enable VP Auditing, select the events, and select Save.
The receiver stores the same record twice.Delivery is at least once, so a record can be delivered again after a restart.Deduplicate on event_id in the receiver.
Records from an outage period never arrive.The integration’s delivery limits skipped them, or the backlog grew past its cap.Raise or clear Give up on a record after and Skip records older than if your destination must receive every record.
After re-enabling an integration, records from while it was disabled are missing.Disabling the integration or its endpoint pauses delivery and lets go of the records it has not received.Keep the integration enabled during maintenance windows when the records matter, and use the Audit page for that period.
The form asks for a whole number of 1 or more under a delivery limit, and saving fails.A delivery limit holds zero, a decimal, or text.Enter a whole number of 1 or more, or clear the field.

Next steps

  • Audit log: what each audit event records and how records tie to signed presentations.
  • Set up event notifications: send lifecycle alerts, such as new users or connection point changes, to the same destinations.