Webhooks allow you to receive real-time notifications when events occur in the Veritas platform.
Overview#
Instead of polling the API for changes, configure webhooks to receive HTTP POST requests when:
- New articles match your alert criteria
- Entities you're tracking are mentioned
- New fact-checks are published
- Breaking news occurs
Setting Up Webhooks#
1. Create an Alert Subscription#
const subscription = await client.alerts.create({
name: 'Breaking Politics News',
alertType: 'breaking_news',
filters: {
categories: ['politics'],
languages: ['en'],
},
webhookUrl: 'https://your-server.com/webhooks/veritas',
frequency: 'instant',
});
2. Configure Your Endpoint#
Your webhook endpoint must:
- Accept HTTP POST requests
- Respond with 2xx status within 30 seconds
- Handle duplicate deliveries idempotently
- Verify webhook signatures (recommended)
Example Express.js Handler:
const express = require('express');
const crypto = require('crypto');
const app = express();
app.use(express.raw({ type: 'application/json' }));
app.post('/webhooks/veritas', (req, res) => {
// Verify signature
const signature = req.headers['x-veritas-signature'];
const timestamp = req.headers['x-veritas-timestamp'];
if (!verifySignature(req.body, signature, timestamp)) {
return res.status(401).send('Invalid signature');
}
// Parse payload
const payload = JSON.parse(req.body);
// Process the webhook
console.log('Received webhook:', payload.notificationType);
console.log('Article:', payload.article?.headline);
// Acknowledge receipt
res.status(200).send('OK');
// Process asynchronously
processWebhook(payload);
});
function verifySignature(body, signature, timestamp) {
const secret = process.env.VERITAS_WEBHOOK_SECRET;
const payload = `${timestamp}.${body}`;
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(`sha256=${expected}`)
);
}
Webhook Payload#
All webhook payloads follow this structure:
{
"id": "notif_abc123",
"subscriptionId": "sub_xyz789",
"notificationType": "keyword",
"title": "New article matches your keywords",
"summary": "Article about election results matches 'election, voting'",
"payload": {
"articleId": "article_001",
"headline": "Election Results Announced",
"publishedAt": "2024-01-15T14:30:00Z",
"matchedKeywords": ["election", "voting"],
"source": {
"name": "Global News Network",
"domain": "gnn.com"
}
},
"createdAt": "2024-01-15T14:30:05Z"
}
Payload Fields#
| Field | Type | Description |
|---|---|---|
id |
string | Unique notification ID |
subscriptionId |
string | Alert subscription that triggered this |
notificationType |
string | Type of alert (keyword, entity_mention, etc.) |
title |
string | Human-readable notification title |
summary |
string | Brief description |
payload |
object | Event-specific data |
createdAt |
string | When the notification was created |
Payload by Notification Type#
Keyword Alert:
{
"notificationType": "keyword",
"payload": {
"articleId": "article_001",
"headline": "Article headline",
"publishedAt": "2024-01-15T14:30:00Z",
"matchedKeywords": ["keyword1", "keyword2"],
"source": { "name": "Source Name", "domain": "source.com" }
}
}
Entity Mention:
{
"notificationType": "entity_mention",
"payload": {
"articleId": "article_001",
"headline": "Article headline",
"publishedAt": "2024-01-15T14:30:00Z",
"entityId": "ent_001",
"entityName": "Entity Name",
"entityType": "person",
"mentionCount": 5,
"sentiment": 0.3
}
}
Breaking News:
{
"notificationType": "breaking_news",
"payload": {
"articleId": "article_001",
"headline": "Breaking: Major Event Occurs",
"publishedAt": "2024-01-15T14:30:00Z",
"category": "politics",
"source": { "name": "Source Name", "domain": "source.com" }
}
}
Fact Check:
{
"notificationType": "fact_check",
"payload": {
"claimId": "claim_001",
"claimText": "Claim being fact-checked",
"verdict": "false",
"confidence": 0.98,
"publishedAt": "2024-01-15T14:30:00Z"
}
}
Webhook Headers#
Each webhook request includes these headers:
| Header | Description |
|---|---|
Content-Type |
application/json |
X-Veritas-Signature |
HMAC signature for verification |
X-Veritas-Timestamp |
Request timestamp (Unix epoch) |
X-Veritas-Delivery-Id |
Unique delivery attempt ID |
X-Veritas-Event-Type |
Notification type |
User-Agent |
Veritas-Webhook/1.0 |
Signature Verification#
All webhooks are signed using HMAC-SHA256. Verify signatures to ensure authenticity.
Signature Format#
X-Veritas-Signature: sha256=<hex_digest>
Verification Algorithm#
import hmac
import hashlib
def verify_signature(payload: bytes, signature: str, timestamp: str, secret: str) -> bool:
"""Verify webhook signature."""
# Construct the signed payload
signed_payload = f"{timestamp}.{payload.decode('utf-8')}"
# Calculate expected signature
expected = hmac.new(
secret.encode('utf-8'),
signed_payload.encode('utf-8'),
hashlib.sha256
).hexdigest()
# Compare signatures
expected_sig = f"sha256={expected}"
return hmac.compare_digest(signature, expected_sig)
Timestamp Validation#
Reject webhooks with timestamps older than 5 minutes to prevent replay attacks:
function isTimestampValid(timestamp) {
const now = Math.floor(Date.now() / 1000);
const webhookTime = parseInt(timestamp, 10);
const fiveMinutes = 5 * 60;
return Math.abs(now - webhookTime) <= fiveMinutes;
}
Delivery & Retries#
Delivery Guarantees#
- At-least-once delivery - Webhooks may be delivered multiple times
- Order not guaranteed - Events may arrive out of order
Retry Policy#
If your endpoint fails to respond with 2xx, we retry with exponential backoff:
| Attempt | Delay |
|---|---|
| 1 | Immediate |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 12 hours |
After 6 failed attempts, the notification is marked as undeliverable.
Handling Duplicates#
Use the notification id for idempotency:
const processedIds = new Set();
function handleWebhook(payload) {
if (processedIds.has(payload.id)) {
console.log('Duplicate webhook, skipping');
return;
}
processedIds.add(payload.id);
// Process the webhook...
}
Testing Webhooks#
Using the Sandbox#
Test webhooks using sandbox (test) API keys:
// Create a test subscription
const client = new VeritasClient({ apiKey: 'sk_test_...' });
await client.alerts.create({
name: 'Test Alert',
alertType: 'keyword',
filters: { keywords: ['test'] },
webhookUrl: 'https://your-test-endpoint.com/webhook',
});
Local Development#
Use tools like ngrok to expose local endpoints:
# Start ngrok tunnel
ngrok http 3000
# Use the ngrok URL for webhook testing
# https://abc123.ngrok.io/webhooks/veritas
Manual Trigger#
Trigger a test webhook via the sandbox API:
// Force a notification (sandbox only)
await client.sandbox.forceWebhook({
subscriptionId: 'sub_001',
notificationType: 'keyword',
payload: {
articleId: 'test_article',
headline: 'Test Article',
matchedKeywords: ['test'],
},
});
Webhook Security Best Practices#
- Always verify signatures - Reject unsigned or invalid webhooks
- Validate timestamps - Prevent replay attacks
- Use HTTPS - Never expose webhook endpoints over HTTP
- Implement idempotency - Handle duplicate deliveries
- Respond quickly - Return 200 immediately, process async
- Keep secrets secure - Store webhook secrets in environment variables
- Monitor failures - Alert on repeated delivery failures
- Log webhook data - Maintain audit trail for debugging
Managing Webhook URLs#
Update Webhook URL#
await client.alerts.update(subscriptionId, {
webhookUrl: 'https://new-endpoint.com/webhook',
});
Disable Webhooks (Use Email Instead)#
await client.alerts.update(subscriptionId, {
webhookUrl: null,
email: 'alerts@example.com',
});
View Delivery History#
// Get recent notifications with delivery status
const notifications = await client.alerts.notifications({
subscriptionId: 'sub_001',
delivered: false, // Show failed deliveries
});
Troubleshooting#
Webhook Not Received#
- Check subscription is active:
await client.alerts.get(subscriptionId) - Verify webhook URL is accessible from the internet
- Check your server logs for incoming requests
- Review notification history for delivery attempts
Invalid Signature#
- Ensure you're using the raw request body (not parsed JSON)
- Verify your webhook secret is correct
- Check timestamp is being included in signature calculation
Duplicate Deliveries#
- Implement idempotency using notification ID
- Check for multiple active subscriptions with same filters
- Review retry logs for failed initial delivery
Support#
For webhook issues, contact api-support@veritas.news with:
- Subscription ID
- Notification IDs (if available)
- Webhook endpoint URL
- Error messages or response codes
- Timestamps of issues