Webhooks API
Receive real-time notifications about security events.
Create Webhook
POST /v1/webhookscurl https://api.talonai.io/v1/webhooks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-app.com/webhooks/talonai",
"events": ["threat.detected", "policy.violated"],
"secret": "your-webhook-secret"
}'Webhook Events
| Event | Description |
|---|---|
| threat.detected | High-risk content detected |
| threat.blocked | Request was blocked |
| policy.violated | Policy rule triggered |
| pii.detected | PII found in content |
| rate_limit.exceeded | Rate limit hit |
Webhook Payload
{
"id": "evt_abc123",
"type": "threat.detected",
"created": "2024-01-15T10:30:00Z",
"data": {
"analysisId": "analysis_xyz789",
"riskScore": 85,
"riskLevel": "high",
"threats": [
{
"type": "prompt_injection",
"confidence": 0.92,
"description": "Detected instruction override attempt"
}
],
"content": "[truncated]",
"metadata": {
"userId": "user_123",
"sessionId": "sess_abc"
}
}
}Verifying Webhooks
Verify webhook signatures to ensure authenticity:
import crypto from 'crypto';
function verifyWebhook(payload: string, signature: string, secret: string) {
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
// Express handler
app.post('/webhooks/talonai', (req, res) => {
const signature = req.headers['x-talonai-signature'];
if (!verifyWebhook(JSON.stringify(req.body), signature, WEBHOOK_SECRET)) {
return res.status(401).send('Invalid signature');
}
// Process webhook
console.log('Event:', req.body.type);
res.status(200).send('OK');
});Best Practices
- Always verify webhook signatures
- Respond with 200 quickly, process async
- Implement idempotency using event IDs
- Set up retry handling for failures