Event Hooks & Webhooks

Subscribe to platform events and receive real-time notifications when executions complete, security threats are detected, or budget thresholds are reached.

Overview

VeriPrompt's event system lets you:

• Monitor gateway executions in real-time
• Get alerted on security threats automatically
• Track budget usage with warning thresholds
• Trigger external workflows via webhooks

Access and Permissions

Required roles: Account Owner, Admin

UI Path: Admin > Webhooks

Event Types

Event	Trigger	Payload
EXECUTION_COMPLETED	Successful gateway execution	Provider, model, tokens, latency, cost
EXECUTION_FAILED	All providers failed	Error message, error code
SECURITY_THREAT_DETECTED	Protective prompt flagged a threat	Threat type, severity, blocked status
TOKEN_BUDGET_WARNING	Usage approaching budget limit	Current usage, budget limit, percent used
TOKEN_BUDGET_EXCEEDED	Budget limit reached	Usage details
POLICY_UPDATED	Routing policy changed	Policy ID, change details
PROVIDER_DEGRADED	Provider health issues	Provider name, error rate
PROVIDER_RECOVERED	Provider health restored	Provider name
GEOFENCING_VIOLATION	Request violated geo rules	Request origin, blocked region

Setting Up Webhooks

1. Create a webhook subscription

cURL

curl -X POST https://app.veriprompt.tech/api/v1/events \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Security Alerts",
    "url": "https://your-app.com/webhooks/veriprompt",
    "eventTypes": ["SECURITY_THREAT_DETECTED", "GEOFENCING_VIOLATION"],
    "secret": "your-webhook-secret"
  }'

JavaScript

const response = await fetch('/api/v1/events', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Security Alerts',
    url: 'https://your-app.com/webhooks/veriprompt',
    eventTypes: ['SECURITY_THREAT_DETECTED', 'GEOFENCING_VIOLATION'],
    secret: 'your-webhook-secret'
  })
});
const subscription = await response.json();

Python

import requests

response = requests.post(
    'https://app.veriprompt.tech/api/v1/events',
    headers={'Authorization': 'Bearer YOUR_TOKEN'},
    json={
        'name': 'Security Alerts',
        'url': 'https://your-app.com/webhooks/veriprompt',
        'eventTypes': ['SECURITY_THREAT_DETECTED', 'GEOFENCING_VIOLATION'],
        'secret': 'your-webhook-secret'
    }
)
subscription = response.json()

2. Receive webhook deliveries

Webhook payloads are sent as POST requests to your URL:

{
  "eventType": "SECURITY_THREAT_DETECTED",
  "companyId": "company_xxx",
  "sourceType": "gateway",
  "payload": {
    "threatType": "prompt_injection",
    "severity": "high",
    "description": "Detected instruction override attempt",
    "blocked": true
  },
  "occurredAt": "2026-02-15T20:30:00Z"
}

3. Verify webhook signatures

If you set a webhook secret, verify the signature in the X-Webhook-Signature header:

JavaScript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return expected === signature;
}

// In your webhook handler
app.post('/webhooks/veriprompt', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  if (!verifyWebhookSignature(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  // Process the event
  console.log('Event:', req.body.eventType);
  res.status(200).json({ received: true });
});

Python

import hmac
import hashlib
import json

def verify_webhook_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        json.dumps(payload).encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# In your webhook handler (Flask example)
@app.route('/webhooks/veriprompt', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Webhook-Signature')
    if not verify_webhook_signature(request.json, signature, WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401
    # Process the event
    print('Event:', request.json['eventType'])
    return jsonify({'received': True}), 200

WARNING

Always verify webhook signatures in production. Without signature verification, an attacker could send forged events to your webhook endpoint.

Event Filtering

Use event matchers to filter which events trigger your webhook:

Filter	Description
eventType	Match specific event types
sourceType	Filter by source (gateway, agent, synthetic)
filterJson	Custom field-level filters on the payload

TIP

Combine multiple event types in a single subscription to reduce the number of webhooks you need to manage. For example, subscribe to both TOKEN_BUDGET_WARNING and TOKEN_BUDGET_EXCEEDED in one subscription to handle all budget-related events.

Managing Subscriptions

List active subscriptions

cURL

curl https://app.veriprompt.tech/api/v1/events \
  -H "Authorization: Bearer YOUR_TOKEN"

JavaScript

const response = await fetch('/api/v1/events', {
  headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
});
const subscriptions = await response.json();

Python

import requests

response = requests.get(
    'https://app.veriprompt.tech/api/v1/events',
    headers={'Authorization': 'Bearer YOUR_TOKEN'}
)
subscriptions = response.json()

Delete a subscription

cURL

curl -X DELETE https://app.veriprompt.tech/api/v1/events/sub_xxx \
  -H "Authorization: Bearer YOUR_TOKEN"

JavaScript

await fetch('/api/v1/events/sub_xxx', {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
});

Python

import requests

requests.delete(
    'https://app.veriprompt.tech/api/v1/events/sub_xxx',
    headers={'Authorization': 'Bearer YOUR_TOKEN'}
)

Learn More

• Security DMZ Layer — Security threat detection
• Analytics & Reporting — Usage monitoring
• Compliance Tools — Compliance event handling