Webhook Integration Guide

Webhooks allow your application to receive real-time notifications when events occur in VeriPrompt.

1. Creating a Webhook

Register a webhook via POST /api/v1/webhooks. This endpoint requires session authentication (via the dashboard).

curl -X POST https://app.veriprompt.tech/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Webhook",
    "url": "https://hooks.example.com/veriprompt",
    "events": ["prompt.executed", "gateway.executed"],
    "secret": "your-secret-minimum-16-chars"
  }'

Required Fields

Field	Type	Description
name	string	Display name for the webhook
url	string	HTTPS endpoint to receive events
events	string[]	Array of event types to subscribe to

Optional Fields

Field	Type	Description
secret	string	HMAC signing secret (minimum 16 characters). If omitted, one is auto-generated and returned in the response.

Available Event Types

Event	Description
prompt.executed	A stored prompt was executed
prompt.created	A new prompt was created
prompt.deleted	A prompt was deleted
gateway.executed	A gateway execution completed
analytics.cost.threshold	Cost threshold was reached
compliance.failed	Compliance check failed

Response

{
  "webhook": {
    "id": "wh_abc123",
    "name": "My Webhook",
    "url": "https://hooks.example.com/veriprompt",
    "events": ["prompt.executed", "gateway.executed"],
    "secret": "your-full-secret-shown-once",
    "isActive": true,
    "createdAt": "2026-01-15T10:30:00Z"
  }
}

Important: The full secret is only returned once at creation time. Store it securely.

2. Managing Webhooks

List All Webhooks

GET /api/v1/webhooks

Returns an array of all registered webhooks for your company.

Delete a Webhook

DELETE /api/v1/webhooks/{webhookId}

Note: Individual webhook retrieval (GET /api/v1/webhooks/{id}) and updates (PUT /api/v1/webhooks/{id}) are not currently supported. Use the list endpoint to view webhook details, and delete/recreate to modify a webhook.

3. Payload Structure & Signature Header

Webhook deliveries include a signature header for verification:

• Header: X-Veriprompt-Signature in the format t=<unixTimestamp>,s=<hexSignature>

Example Payload

{
  "event": "prompt.executed",
  "id": "evt_01J9Y8X3ZZKD",
  "attempt": 1,
  "createdAt": "2026-01-15T15:30:09.000Z",
  "data": {
    "promptId": "prompt_123_abc",
    "executionTimeMs": 1250,
    "provider": "openai",
    "model": "gpt-4o",
    "tokensUsed": 145
  }
}

Signature Calculation

The signature is calculated as:

HMAC_SHA256(timestamp + '.' + rawPayload, secret)

4. Verifying Webhooks

Node.js / Next.js

import { verifySignature } from '@/lib/webhooks/signature';

export async function POST(req: Request) {
  const secret = process.env.VERIPROMPT_WEBHOOK_SECRET!;
  const signature = req.headers.get('x-veriprompt-signature') ?? '';
  const body = await req.arrayBuffer();

  const isValid = verifySignature({
    payload: Buffer.from(body),
    secret,
    signatureHeader: signature,
    toleranceSeconds: 300, // Reject deliveries older than 5 minutes
  });

  if (!isValid) {
    return new Response('Invalid signature', { status: 400 });
  }

  const event = JSON.parse(Buffer.from(body).toString('utf8'));
  // Handle event...
  return new Response('ok');
}

Express.js

import express from 'express';
import { verifySignature } from '@/lib/webhooks/signature';

const app = express();
app.use(express.raw({ type: 'application/json' }));

app.post('/webhooks/veriprompt', (req, res) => {
  const valid = verifySignature({
    payload: req.body,
    secret: process.env.VERIPROMPT_WEBHOOK_SECRET!,
    signatureHeader: req.header('x-veriprompt-signature') ?? '',
  });

  if (!valid) return res.status(400).send('Invalid signature');

  const event = JSON.parse(req.body.toString());
  // Handle event...
  res.sendStatus(200);
});

5. Retry & Error Handling

• VeriPrompt retries failed deliveries up to 3 times with exponential backoff:
  • 1st retry: after 1 minute
  • 2nd retry: after 5 minutes
  • 3rd retry: after 15 minutes
• Always return a 2xx response after processing. Non-2xx triggers retries.
• Use GET /api/v1/webhooks/deliveries to inspect delivery history.

6. Security Best Practices

1. Store secrets securely - Use an encrypted secret manager, never hardcode.
2. Enforce HTTPS - Only use HTTPS endpoints with valid TLS certificates.
3. Validate signatures - Always verify the X-Veriprompt-Signature header before processing.
4. Check timestamps - Reject events older than 5 minutes to prevent replay attacks.
5. Validate payloads - Check the event type before processing data.
6. Log deliveries - Keep an audit trail of received webhook events.

Related Docs

• Error Handling
• Monitoring & Health