POST
/
v1
/
integrations
/
webhooks
Configure Webhooks
curl --request POST \
  --url https://api.example.com/v1/integrations/webhooks \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "events": [
    {}
  ],
  "secret": "<string>",
  "headers": {},
  "config": {
    "retryPolicy": {
      "maxAttempts": 123,
      "initialDelay": 123,
      "backoffMultiplier": 123
    },
    "timeout": 123,
    "active": true,
    "batchEvents": true,
    "includeFullData": true
  }
}
'
{
  "400": {},
  "422": {},
  "webhookId": "<string>",
  "url": "<string>",
  "secret": "<string>",
  "events": [
    {}
  ],
  "status": "<string>",
  "testResult": {
    "success": true,
    "statusCode": 123,
    "responseTime": 123,
    "error": "<string>"
  }
}

​
Configure Webhooks

Configure webhook endpoints to receive real-time notifications about events in AuthentiVoice.

​
Request

​
url
string
required
HTTPS endpoint URL to receive webhook events
​
events
array
required
List of events to subscribe to
  • analysis.started - Analysis processing started
  • analysis.completed - Analysis completed successfully
  • analysis.failed - Analysis failed
  • fraud.detected - High-risk fraud detected
  • review.assigned - Review assigned to user
  • review.completed - Review completed
  • review.escalated - Review escalated
  • integration.error - Integration error occurred
  • user.action - Significant user action
​
secret
string
Webhook signing secret for payload verification (auto-generated if not provided)
​
headers
object
Custom headers to include with webhook requests
​
config
object
Webhook configuration options

​
Response

​
webhookId
string
Unique identifier for the webhook
​
url
string
Configured webhook URL
​
secret
string
Webhook signing secret (only shown once)
​
events
array
Subscribed events
​
status
string
Webhook status: active, inactive, failed
​
testResult
object
Test delivery result

​
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"
}

​
Webhook Payload Format

All webhook events follow this structure: 
{
  "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

​
400
Bad Request
Invalid webhook configuration
{
  "error": {
    "code": "INVALID_URL",
    "message": "Webhook URL must use HTTPS"
  }
}
​
422
Unprocessable Entity
Webhook test failed
{
  "error": {
    "code": "WEBHOOK_TEST_FAILED",
    "message": "Failed to deliver test webhook",
    "details": {
      "statusCode": 404,
      "error": "Endpoint not found"
    }
  }
}