Skip to main content
PromptReports.AI

Webhooks

Integrate PromptReports with your external systems using webhooks. Receive real-time notifications when prompts are created, updated, evaluated, or promoted.

What are Webhooks?#

Webhooks are HTTP callbacks that send real-time notifications to your systems when events occur in PromptReports. Instead of polling for changes, your application receives instant updates when prompts are modified, versions are promoted, or evaluations complete.

Real-Time Updates

Receive instant notifications without polling or delays.

Secure Delivery

HMAC signatures ensure payloads are authentic and unmodified.

Automatic Retry

Failed deliveries are automatically retried with exponential backoff.

Delivery History

Track all webhook deliveries with status codes and responses.

Creating Webhooks#

You can create webhooks at the folder level or globally for your account:

1

Navigate to Webhooks

Go to your folder settings or account settings and find the Webhooks section.
2

Click "Create Webhook"

Open the webhook creation dialog.
3

Configure the webhook

  • Name: A descriptive name for this webhook
  • URL: The HTTPS endpoint to receive events
  • Events: Which events should trigger this webhook
  • Secret: Optional secret for HMAC signature verification
4

Test the webhook

Send a test payload to verify your endpoint is working.

Event Types#

Subscribe to the events that matter for your integration:

EventDescriptionTriggered When
prompt.createdNew prompt createdA new prompt is added to a folder
prompt.updatedPrompt content modifiedDraft changes are saved
version.createdNew version savedA version is saved from draft
version.promotedVersion promoted to new stageVersion moves to staging/production
evaluation.startedEvaluation begunA batch evaluation starts running
evaluation.completedEvaluation finishedEvaluation completes with results
approval.requestedApproval requestedSomeone requests promotion approval
approval.completedApproval decision madeApprover accepts or rejects request

Payload Structure#

All webhook payloads follow a consistent structure:

Webhook Payload Example
json
{
  "id": "wh_evt_abc123",
  "type": "version.promoted",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "promptId": "prm_xyz789",
    "promptName": "Customer Support Response",
    "versionId": "ver_def456",
    "versionNumber": 5,
    "previousStage": "staging",
    "newStage": "production",
    "promotedBy": {
      "id": "usr_ghi012",
      "name": "Jane Smith",
      "email": "jane@example.com"
    }
  },
  "metadata": {
    "folderId": "fld_jkl345",
    "folderName": "Production Prompts"
  }
}
FieldTypeDescription
idstringUnique event identifier (for deduplication)
typestringEvent type (e.g., "version.promoted")
timestampstringISO 8601 timestamp of when event occurred
dataobjectEvent-specific data payload
metadataobjectAdditional context (folder info, etc.)

Signature Verification#

When you provide a secret, PromptReports signs each payload using HMAC-SHA256. Always verify signatures to ensure payloads are authentic.

Signature Verification (Node.js)
typescript
import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler:
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-promptreports-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifyWebhookSignature(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process the webhook...
  res.status(200).json({ received: true });
});

Testing Webhooks#

Test your webhook integration before going live:

1

Use the Test button

Click "Test" on any webhook to send a sample payload to your endpoint.
2

Check delivery history

View the delivery history to see response codes and any error messages.
3

Inspect payloads

Review the exact payload that was sent to debug integration issues.
4

Use a tunnel for local development

Tools like ngrok let you receive webhooks on your local machine during development.

Best Practices#

Always Verify Signatures

Never trust webhook payloads without verifying the HMAC signature.

Respond Quickly

Return 2xx within 30 seconds. Process heavy work asynchronously.

Handle Duplicates

Use the event ID for idempotency—events may be delivered more than once.

Handle Failures Gracefully

Return 4xx for client errors, 5xx for server errors. We'll retry 5xx.

PreviousAutomation Overview
NextMedia Generation