Create Webhook

Create an organization outbound webhook. Vonative POSTs selected call lifecycle events to this URL.

Endpoint

POST /v1/webhooks

Request body

url

string

required

HTTPS endpoint URL.

events

array

required

One or more event types: status-update, call.started, assistant.started, call.ended, end-of-call-report, or error.

description

string

Optional description.

Example request

curl -X POST https://api.vonative.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://myapp.com/webhook/vonative",
    "events": ["call.started", "end-of-call-report", "error"]
  }'

Response

{
  "success": true,
  "data": {
    "id": "wh-uuid-1234",
    "url": "https://myapp.com/webhook/vonative",
    "status": "active",
    "secret": "whsec_..."
  }
}

The secret is used to verify webhook signatures.

Event contracts

Every delivery has this envelope:

{
  "message": {
    "type": "EVENT_TYPE",
    "timestamp": 1767600000000,
    "call": { "id": "call-uuid", "metadata": { "session_id": 123 } }
  }
}

timestamp is Unix milliseconds. call.metadata contains caller-supplied/session metadata when available. Treat fields other than message.type and message.call.id as optional: delivery can happen before a provider supplies all information.

Event	Additional fields	Purpose
`call.started`	`call.status`, `call.startedAt`, `call.customer`, `call.phoneNumber`, `assistant`	A call is in progress.
`assistant.started`	`startedAt`, `newAssistant`, `call.assistantId`	The configured assistant joined the call.
`status-update`	`call.status`	A lifecycle status changed.
`call.ended`	`call.endedAt`, `call.endedReason`, `call.duration`	The call ended; final reporting can follow.
`end-of-call-report`	`analysis`, `artifact`, cost and localization fields	Final call report, including available artifacts and analysis.
`error`	`error.message`, `error.sourceEvent`	Processing or delivery failure context.

End-of-call report

end-of-call-report is the canonical final-report event. It has the standard envelope plus the following optional objects:

{
  "message": {
    "type": "end-of-call-report",
    "timestamp": 1767600000000,
    "call": {
      "id": "call-uuid",
      "status": "ended",
      "startedAt": "2026-01-05T10:00:00Z",
      "endedAt": "2026-01-05T10:00:42Z",
      "endedReason": "customer-ended-call",
      "duration": 42.1,
      "cost": 87.03702,
      "currency": "NGN",
      "costBreakdown": {
        "stt": 11.55,
        "llm": 2.211,
        "tts": 0,
        "boboyii_fee": 73.27602,
        "total": 87.03702
      },
      "metadata": { "session_id": 123 }
    },
    "analysis": {
      "summary": "Caller received the requested account update.",
      "successEvaluation": "true"
    },
    "artifact": {
      "transcript": "User: Hello\\nAssistant: Hi there",
      "recordingUrl": "https://storage.example.com/recordings/call-uuid.wav",
      "messages": []
    },
    "costCurrency": "NGN",
    "exchangeRate": 1550,
    "boboyii": {
      "sessionId": 123,
      "organizationId": 1,
      "customerCostUsd": 0.056153,
      "localizedCostBreakdown": {
        "stt": 11.55,
        "llm": 2.211,
        "tts": 0,
        "boboyii_fee": 73.27602,
        "total": 87.03702
      }
    }
  }
}

analysis is present only when the relevant analysis/summary output is produced. artifact.transcript requires retained call text and can be redacted by compliance rules. artifact.recordingUrl requires recording to be enabled and an available recording artifact; it can be withheld when audio redaction fails. Cost and localization fields are present only when cost calculation and currency conversion data are available.

Assistant callbacks and organization webhooks

Organization webhooks are created with this endpoint and receive their subscribed events. An Assistant can independently set server.url and select server_messages for per-assistant callbacks. They use the same event envelope, but configuring one does not configure the other.

Authentication

Introduction

Assistants

Phone Numbers

Workflows

Calls

Meets

Files

Tools

Server Credentials

Sessions

Call Logs

Webhooks

Campaigns

Create Webhook

Create Webhook

Endpoint

Request body

Example request

Response

Event contracts

End-of-call report

Assistant callbacks and organization webhooks

​Create Webhook

​Endpoint

​Request body

​Example request

​Response

​Event contracts

​End-of-call report

​Assistant callbacks and organization webhooks

Create Webhook

Endpoint

Request body

Example request

Response

Event contracts

End-of-call report

Assistant callbacks and organization webhooks