Webhooks let your application receive real-time notifications when PromptGuard detects security events — blocked requests, detections at confidence 0.8 or above, and Shadow AI devices that fail open.
Overview
When you configure a webhook for a project, PromptGuard sends HTTP POST requests to your endpoint whenever specific security events occur. This lets you:- Log security events to your own systems
- Trigger alerts in Slack, PagerDuty, or other tools
- Build custom dashboards and analytics
- Audit AI interactions in real-time
Setup
Via Dashboard
- Go to app.promptguard.co
- Select your project
- Open the project’s Settings, section Alert delivery
- Enter your URL under Default webhook on the Alert destinations card
- Click Save webhook
PagerDuty
PagerDuty’s Events API v2 authenticates on an integration key inside each payload, so a PagerDuty destination needs one, and it is stored as a credential, never on the destination itself:- Under Provider keys, add a key with provider PagerDuty and paste the Events API v2 integration key. It is encrypted at rest and shown only by prefix afterwards.
- On the project’s Alert destinations card (Settings → Alert delivery), add
https://events.pagerduty.com/v2/enqueueas a destination and choose that credential, or pick Store a new integration key to do both in place. The SIEM Integrations PagerDuty template does both steps in one save.
Delivery Monitoring
Track webhook delivery status in the dashboard:- Open your project’s Settings and, under Alert delivery, follow the delivery log link to Webhook Deliveries
- View delivery history with status, attempts, and errors
- Manually retry failed deliveries
- Status: Pending, delivered, or failed
- Attempts: Number of delivery attempts (auto-retries with exponential backoff)
- Response Status: HTTP status code from your endpoint
- Error Details: Last error message for failed deliveries
Via API
/dashboard/* takes a dashboard sign-in, not an API key. These endpoints are the API the dashboard at app.promptguard.co calls. They are not part of the public API, and no API key or long-lived token works on them. Everything under /api/v1 takes your X-API-Key instead (API reference).To script one anyway, sign in with your email and password. This needs an account that has a password, and an email domain that requires SSO is refused. The access token lasts one hour.YOUR_SESSION_TOKEN or YOUR_SESSION_COOKIE, it means the access_token from step 1, sent as Authorization: Bearer <token> or as the access_token cookie. A request acts on your personal organization unless it sends X-Organization-Id.provider: generic,
slack, pagerduty, datadog or splunk. Left out, a destination keeps the
provider its URL already had, and a new one is generic. A PagerDuty
destination references its stored
credential by id (the id returned by POST /dashboard/provider-keys with
"provider": "pagerduty"); the key itself is never part of the channel:
needs_credential flag: true
marks a PagerDuty destination that has no usable credential and is not being
delivered to.
What a delivery contains
Every alert is the SIEM event: the threat, the decision, and the Organization, project, Device and event it came from, with a link that opens the event in its Organization. An alert is sent for a threat that was blocked, or found with confidence 0.8 or higher.Verifying deliveries
Generate a signing secret on the project’s Delivery security card and every delivery carriesX-PromptGuard-Timestamp and X-PromptGuard-Signature. The
construction, a 5-minute replay window, and verification code for Python and
Node are in SIEM export.
Without a secret, deliveries are unsigned: treat them as unauthenticated input.
Best Practices
- Respond quickly — Return a
200status within 10 seconds, or the attempt counts as failed. Process events asynchronously if needed. - Handle duplicates — Use
event_idto deduplicate events in case of retries. - Verify the signature — Over the raw body, before parsing it.
- Use HTTPS — Always use HTTPS endpoints for webhook delivery.
- Monitor failures — Track webhook delivery failures in your monitoring system.
Retry Policy
If your endpoint returns a non-2xx status code or does not answer within 10 seconds, PromptGuard tries again. A delivery is attempted three times in all:
After the third failure the delivery is marked failed, and shown with its error
on the project’s Webhook Deliveries page, where you can retry it.
Changing a verdict
Webhooks are notifications: PromptGuard sends them after it has decided, and does not wait for or read a reply. To change what PromptGuard allows or blocks, change the project’s policies and guardrails, or use an LLM Guard policy for a rule described in plain English.Next Steps
Monitoring Dashboard
View security events and analytics
Usage Tracking
Monitor your API usage