Webhooks

Voxxi can send event notifications to your endpoint when call processing completes or fails.

Overview

Configure webhook endpoints in Voxxi Integrations. Each endpoint subscribes to one or more events.

Event types

Name
call.analysis_complete
Description
Fired when call analysis finishes successfully.
Name
call.analysis_failed
Description
Fired when analysis fails.
Name
call.ingestion_failed
Description
Fired when recording ingestion fails.

Headers

Webhook deliveries are POST requests with JSON body and these headers:

Name
X-Voxxi-Event
Type
string
Description
Event name, for example call.analysis_complete.
Name
X-Voxxi-Timestamp
Type
string
Description
Unix timestamp (seconds) used in signature generation.
Name
X-Voxxi-Signature
Type
string
Description
Signature in the format v1=<hex_hmac_sha256>.
Name
X-Voxxi-Delivery-Id
Type
string
Description
Unique id for this delivery attempt.

Payload envelope

{
  "id": "delivery_uuid",
  "type": "call.analysis_complete",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "data": {
    "callId": "call_uuid",
    "organizationId": "org_uuid"
  }
}

data fields vary by event type. call.analysis_complete includes analysis results, transcript/extractions, tags, and metadata.

Signature verification

The signature is HMAC-SHA256 over:

<timestamp>.<raw_request_body>

using your webhook signing secret.

Verify X-Voxxi-Signature

import crypto from 'crypto'

function verifyVoxxiSignature({ secret, timestamp, rawBody, signatureHeader }) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')

  const provided = signatureHeader?.replace(/^v1=/, '')
  return Boolean(provided) && crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(provided, 'hex')
  )
}