Webhooks let your application receive real-time notifications when PromptGuard detects security events — threats blocked, PII redacted, usage thresholds crossed, and more.
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
- Navigate to Settings or Project Overview
- Enter your Webhook URL
- Save
Via API
curl -X PATCH https://api.promptguard.co/dashboard/projects/{project_id}/webhook \
-H "Cookie: session=YOUR_SESSION" \
-H "Content-Type: application/json" \
-d '{
"webhook_url": "https://your-app.com/webhooks/promptguard",
"webhook_enabled": true
}'
Event Types
| Event | Triggered When |
|---|
threat.blocked | A request is blocked by security policy |
threat.detected | A threat is detected (even if allowed) |
pii.redacted | PII is detected and redacted from content |
usage.threshold | Usage crosses 80% or 100% of monthly quota |
usage.overage | Usage exceeds monthly quota (Scale plan) |
{
"event": "threat.blocked",
"timestamp": "2025-02-08T14:30:00Z",
"project_id": "proj_abc123",
"data": {
"event_id": "evt_xyz789",
"decision": "block",
"threat_type": "prompt_injection",
"confidence": 0.95,
"reason": "Instruction override pattern detected",
"request_metadata": {
"model": "gpt-5-nano",
"ip_address": "203.0.113.42"
}
}
}
Threat Blocked
{
"event": "threat.blocked",
"timestamp": "2025-02-08T14:30:00Z",
"project_id": "proj_abc123",
"data": {
"event_id": "evt_xyz789",
"decision": "block",
"threat_type": "prompt_injection",
"confidence": 0.95,
"reason": "Instruction override pattern detected"
}
}
PII Redacted
{
"event": "pii.redacted",
"timestamp": "2025-02-08T14:32:00Z",
"project_id": "proj_abc123",
"data": {
"event_id": "evt_abc456",
"pii_types": ["email", "phone"],
"redaction_count": 2,
"direction": "input"
}
}
Usage Threshold
{
"event": "usage.threshold",
"timestamp": "2025-02-08T14:35:00Z",
"project_id": "proj_abc123",
"data": {
"current_usage": 80500,
"monthly_limit": 100000,
"percentage": 80.5,
"plan": "pro"
}
}
Handling Webhooks
Example Server (Node.js)
import express from 'express';
const app = express();
app.use(express.json());
app.post('/webhooks/promptguard', (req, res) => {
const { event, data, timestamp } = req.body;
switch (event) {
case 'threat.blocked':
console.log(`[BLOCKED] ${data.threat_type} (confidence: ${data.confidence})`);
// Send to Slack, PagerDuty, etc.
break;
case 'pii.redacted':
console.log(`[PII] Redacted ${data.redaction_count} items: ${data.pii_types.join(', ')}`);
break;
case 'usage.threshold':
console.log(`[USAGE] ${data.percentage}% of monthly quota used`);
if (data.percentage >= 90) {
// Alert team about approaching limit
}
break;
}
res.status(200).json({ received: true });
});
app.listen(3000);
Example Server (Python)
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/webhooks/promptguard', methods=['POST'])
def handle_webhook():
payload = request.json
event = payload['event']
data = payload['data']
if event == 'threat.blocked':
print(f"[BLOCKED] {data['threat_type']} (confidence: {data['confidence']})")
# Send to logging/alerting system
elif event == 'pii.redacted':
print(f"[PII] Redacted {data['redaction_count']} items")
elif event == 'usage.threshold':
print(f"[USAGE] {data['percentage']}% of quota used")
if data['percentage'] >= 90:
send_team_alert("Approaching monthly quota limit")
return jsonify({"received": True}), 200
Best Practices
- Respond quickly — Return a
200 status within 5 seconds. Process events asynchronously if needed.
- Handle duplicates — Use
event_id to deduplicate events in case of retries.
- Secure your endpoint — Use HTTPS and validate the source IP or implement a shared secret.
- Log everything — Store raw webhook payloads for debugging and audit trails.
- Monitor failures — Track webhook delivery failures in your monitoring system.
Retry Policy
If your endpoint returns a non-2xx status code or times out, PromptGuard will retry delivery:
| Attempt | Delay |
|---|
| 1st retry | 30 seconds |
| 2nd retry | 2 minutes |
| 3rd retry | 10 minutes |
Next Steps
