Use both if you can: push for speed, and pull with the last cursor you stored to fill in anything a dropped delivery missed. The records are identical, so one SIEM search covers both.
The SIEM event
Every record names where it came from. An MSP routing many clients’ alerts into one SIEM can key onorganization_id, and open the event in that client’s console from dashboard_url.
Which events raise an alert
An alert, pushed or pulled from/api/v1/alerts, is a threat that was blocked or flagged, whatever its confidence, or found with confidence 0.8 or higher. Webhook alerts need a plan that includes them; the pull API does not.
Device fail-open alerts
The Shadow AI agent fails open by default: when it cannot get a verdict from the engine it sends the prompt anyway (see If the engine cannot be reached). When one Device has sent 10 prompts that way that no alert has mentioned yet, every destination on its project gets one event withevent: "device_fail_open" — at most one per Device per hour, each counting only what is new since the last. It carries every routed field above, and:
threat_type is fail_open, decision is allow (the prompts were sent), reason says how many, on which Device and why, and dashboard_url opens the organization’s Shadow AI page. It is pushed only: it is not a stored event, so /api/v1/alerts does not serve it. Like every webhook alert it needs a plan that includes webhook alerts.
Shapes per destination
Each destination on the Alert Routing card has a format. You choose it; it is not inferred from the URL.Verify that a delivery came from PromptGuard
On the project’s Delivery security card, choose Generate. The signing secret is shown once: store it in your receiver. From the next delivery on, every request carries:
To verify, compute the HMAC over the timestamp, a full stop and the raw request body exactly as received, before any JSON parsing, and compare it in constant time. Refuse a timestamp more than 5 minutes from your clock: that is what stops a captured delivery being replayed. Each retry is signed again when it is sent, so a retry is never too old.
Replacing the secret takes effect on the next attempt. Receivers using the old one refuse from then on, so update them together.
Send an auth header
Some collectors authenticate on a header: Splunk HEC wantsAuthorization: Splunk <token>, Datadog wants DD-API-KEY. On the Delivery security card, set the header’s name and value. It is stored encrypted and never shown again, only its name.
The header goes only to destinations whose Auth header switch is on, so a Splunk token is never sent to a Slack URL on the same project. A project has one auth header; a second collector that needs a different one goes on its own project, or behind a URL that carries its own credential.
Splunk HEC
- In Splunk, create an HTTP Event Collector token. Turn indexer acknowledgement off for it: with it on, Splunk also requires a channel header, which deliveries do not send.
- In PromptGuard, open Settings → Integrations → Splunk HEC, enter
https://<your-splunk>:8088/services/collector/eventand the token, and save. That storesAuthorization: Splunk <token>as the project’s auth header and adds a destination with format Splunk HEC and Auth header on. - Optionally generate a signing secret. HEC does not check it, but a forwarder in front of Splunk can.
promptguard:security. For example, every block by client:
Microsoft Sentinel
Sentinel ingests through the Azure Monitor Logs Ingestion API, which authenticates with Microsoft Entra ID rather than a static header. Put a small receiver in front of it:- Create a custom table (for example
PromptGuard_CL) with a data collection rule, as Microsoft’s Logs Ingestion API documentation describes. - Create a Logic App whose trigger is When an HTTP request is received, and give it a managed identity allowed to send to that rule.
- In the Logic App, check the signature (an inline-code or Azure Function step running the verification above), then send the body to the rule.
- In PromptGuard, open Settings → Integrations → Microsoft Sentinel and save the Logic App’s trigger URL. Its
sigquery parameter is the Logic App’s own credential, so no auth header is needed, and the format is Generic JSON.
Pull with an export key
An organization admin creates the key: API keys → Create key, kind SIEM export. It reads every project in the Organization, and can do nothing else: any other request it makes is refused with403 read_only_key. No other key can read these endpoints.
Each page is oldest first:
since (ISO 8601, default 24 hours ago), until, limit (1 to 1000, default 100), and cursor. Store next_cursor and send it back as cursor next time: it is returned on every page, empty ones included, and reading from it never skips or repeats an event however many arrive while you page. Events of a project that has since been deleted are not returned.
The stream sends each event’s cursor as its SSE id, so a client that reconnects with Last-Event-ID (as EventSource does) resumes after the last event it received. A comment line every few seconds keeps idle connections open.
Export keys share your plan’s per-minute rate limit like any other key.