Configure Webhooks
Configure webhook endpoints to receive real-time notifications about events in AuthentiVoice.
Request
HTTPS endpoint URL to receive webhook events
List of events to subscribe to
analysis.started - Analysis processing startedanalysis.completed - Analysis completed successfullyanalysis.failed - Analysis failedfraud.detected - High-risk fraud detectedreview.assigned - Review assigned to userreview.completed - Review completedreview.escalated - Review escalatedintegration.error - Integration error occurreduser.action - Significant user action
Webhook signing secret for payload verification (auto-generated if not provided)
Custom headers to include with webhook requests
Webhook configuration options
Retry configurationShow retryPolicy properties
Initial retry delay in seconds
Exponential backoff multiplier
Request timeout in seconds
Whether webhook is active
Batch multiple events in single request
Include full resource data in events
Response
Unique identifier for the webhook
Webhook signing secret (only shown once)
Webhook status: active, inactive, failed
Test delivery resultShow testResult properties
Whether test was successful
Response time in milliseconds
Examples
curl -X POST https://api.authentivoice.com/v1/integrations/webhooks \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://api.yourapp.com/webhooks/authentivoice",
"events": [
"analysis.completed",
"fraud.detected",
"review.completed"
],
"headers": {
"X-Custom-Header": "CustomValue"
},
"config": {
"retryPolicy": {
"maxAttempts": 5,
"initialDelay": 30
},
"timeout": 45,
"includeFullData": true
}
}'
Response Example
{
"webhookId": "whk_abc123def456",
"url": "https://api.yourapp.com/webhooks/authentivoice",
"secret": "whsec_1a2b3c4d5e6f7g8h9i0j",
"events": [
"analysis.completed",
"fraud.detected",
"review.completed"
],
"status": "active",
"testResult": {
"success": true,
"statusCode": 200,
"responseTime": 245
},
"createdAt": "2024-01-15T15:00:00Z"
}
{
"id": "evt_1234567890",
"type": "analysis.completed",
"timestamp": "2024-01-15T15:30:00Z",
"webhookId": "whk_abc123def456",
"data": {
// Event-specific data
}
}
Event Examples
{
"id": "evt_1234567890",
"type": "analysis.completed",
"timestamp": "2024-01-15T15:30:00Z",
"data": {
"analysisId": "ana_abc123",
"riskScore": 75,
"riskLevel": "high",
"fraudIndicators": ["urgency", "authority_claim"],
"duration": 245.5,
"transcriptionConfidence": 0.95
}
}
Signature Verification
Verify webhook authenticity using HMAC-SHA256:
const crypto = require('crypto');
function verifyWebhookSignature(payload, signature, secret) {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload, 'utf8')
.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-authentivoice-signature'];
const payload = JSON.stringify(req.body);
if (!verifyWebhookSignature(payload, signature, WEBHOOK_SECRET)) {
return res.status(401).send('Invalid signature');
}
// Process webhook
res.status(200).send('OK');
});
Managing Webhooks
List Webhooks
GET /v1/integrations/webhooks
Update Webhook
PUT /v1/integrations/webhooks/{webhookId}
Delete Webhook
DELETE /v1/integrations/webhooks/{webhookId}
Test Webhook
POST /v1/integrations/webhooks/{webhookId}/test
Error Responses
Invalid webhook configuration{
"error": {
"code": "INVALID_URL",
"message": "Webhook URL must use HTTPS"
}
}
Webhook test failed{
"error": {
"code": "WEBHOOK_TEST_FAILED",
"message": "Failed to deliver test webhook",
"details": {
"statusCode": 404,
"error": "Endpoint not found"
}
}
}
