Policy Violation Webhooks
A policy violation webhook calls your URL each time ANTS Platform finds a violation of an AI guardrail policy or raises a Discover AI device alert. Your security automation tool receives a signed JSON payload and runs its playbook: open a case, notify a manager or contain a laptop.
Webhooks fire for:
| Source | When |
|---|---|
| Scheduled Detection | A scheduled detection run finds a violation in stored traces. |
| Real-time Enforcement | A guardrail check blocks a prompt or response inline. |
| Device alerts | A Discover AI device stops reporting for the set time, its browser extension is removed, or its agent is unenrolled. See Tamper and silence alerts. |
You choose which violations are sent with filters on detection category and severity, so only what you select reaches your playbook.
Set up a policy violation webhook
Open Automations
Open the Automations page of the project (/project/<projectId>/automations) and select Create Automation. Give it a name.
Choose the trigger
Set the trigger to Policy violation, then set the filters:
| Filter | Meaning |
|---|---|
| Categories | The categories that fire the webhook: detection categories such as PII, PCI, PHI, Ethics & Bias, Safety and any other category your policies use, and the device alert categories Device silent, Extension removed and Agent unenrolled. Leave empty for all categories. |
| Minimum severity | Only violations at this severity or above are sent. Severities, from highest to lowest: Critical, High, Low, Info. |
The severity of a guardrail violation is the Alert Severity set in the agent's detection policy. Device alerts have no severity. They are sent whenever their category is selected, whatever the minimum severity.
Choose the webhook action
Select Webhook, enter the URL, choose the API Version (v1) and add any Headers your receiver needs. Mark a header as secret to hide its value after saving.
Save and copy the secret
Save the automation. ANTS Platform shows the Webhook Secret once. Copy it into your receiver so it can verify the signature. You can regenerate it later, which invalidates the old one.
Open the automation to see its execution history: status, start time, duration, input and output, and any error. The Active switch turns it on and off.
Payload
Each violation is sent as one HTTP POST with a JSON body:
| Field | Meaning |
|---|---|
id | Unique per delivery. Use it to drop duplicates. |
type | Always policy-violation. |
violation.source | scheduled-detection, realtime-enforcement or device-alert. |
violation.outcome | detected for Scheduled Detection and device alerts, blocked for Real-time Enforcement. |
violation.category | The detection category that matched, or device-silent, extension-removed or agent-unenrolled. |
violation.labels | The entity labels or harm categories that matched. Empty for device alerts. |
violation.severity | CRITICAL, HIGH, LOW or INFO. null for device alerts. |
violation.agent | The agent whose call or trace violated the policy. null for device alerts. |
violation.traceId | The trace that holds the evidence. null for device alerts. |
violation.user | The user on the trace, with the user principal name when it is known. null when the trace has no user. |
violation.device | Hostname, serial number and CrowdStrike Falcon agent ID of the device the user works on, when it is enrolled in Discover AI. null otherwise. Fields that are not known are null. See CrowdStrike Falcon. |
violation.evidenceUrl | A link to the evidence in ANTS Platform: the trace, or the device for a device alert. Opening it needs a signed-in account with access to the project, and reading prompt and response content needs the content permission. |
The payload never contains prompt or response text or the matched values. Analysts follow evidenceUrl to see them, subject to their role.
Headers and signature
| Header | Value |
|---|---|
content-type | application/json |
x-ants-signature | t=<unix timestamp>,v1=<hex signature> |
| Your headers | Any headers you configured |
To verify a delivery, compute HMAC-SHA256(secret, "<t>.<raw request body>") as lowercase hex, where <t> is the timestamp from the header, and compare it with v1. Reject requests with an old t to stop replays.
Delivery and retries
- Your endpoint must answer with status 200 within 10 seconds. Any other status counts as a failure.
- A failed delivery is retried up to 4 attempts in total, with backoff.
- After 5 failed executions in a row, the automation is turned off and a banner on the automation shows the failure. Fix the endpoint and switch it back on.
Consume it from your automation tool
CrowdStrike Falcon Fusion SOAR
Point the webhook at the endpoint your Fusion SOAR workflow receives requests on, and add the authentication header that endpoint requires as a secret header. In the workflow, use violation.device.falconAid to act on the exact host and violation.user.userPrincipalName to find the person, for example to open a case, notify the manager or contain the device. See CrowdStrike Falcon.
Other tools
The same payload works with any tool that accepts an HTTP POST, including Splunk SOAR, Tines and a ServiceNow flow. Verify the signature in the receiving step, then branch on violation.category and violation.severity.
Permissions
Creating, editing and deleting automations needs automations write access: Owner and Security & Compliance among the built-in roles. Viewing them needs read access. See Members & Roles.