Skip to main content
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.
Prefer to watch? This page as a silent, step-by-step video:

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

  1. Go to app.promptguard.co
  2. Select your project
  3. Open the project’s Settings, section Alert delivery
  4. Enter your URL under Default webhook on the Alert destinations card
  5. Click Save webhook
The same Alert destinations card takes any number of further destinations, each with the format it is sent in: generic JSON, Splunk HEC, Datadog, PagerDuty or Slack. You choose the format; it is not inferred from the URL. What each format carries, how to verify a delivery’s signature and how to send an auth header are in SIEM export.

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:
  1. 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.
  2. On the project’s Alert destinations card (Settings → Alert delivery), add https://events.pagerduty.com/v2/enqueue as 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.
A PagerDuty destination without a credential is refused when you save it. One that later loses its credential (the key deactivated or deleted) shows a Needs a credential warning, and alerts to it are skipped, with a log line naming the destination, rather than sent to a guaranteed rejection.

Delivery Monitoring

Track webhook delivery status in the dashboard:
  1. Open your project’s Settings and, under Alert delivery, follow the delivery log link to Webhook Deliveries
  2. View delivery history with status, attempts, and errors
  3. Manually retry failed deliveries
The delivery status page shows:
  • 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.
Where an example shows 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.
Per-destination routing goes through the project settings endpoint, which replaces the whole list. Each destination names its 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:
The response echoes each destination with a 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 carries X-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

  1. Respond quickly — Return a 200 status within 10 seconds, or the attempt counts as failed. Process events asynchronously if needed.
  2. Handle duplicates — Use event_id to deduplicate events in case of retries.
  3. Verify the signature — Over the raw body, before parsing it.
  4. Use HTTPS — Always use HTTPS endpoints for webhook delivery.
  5. 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
Last modified on November 8, 2026