Webhooks

CallVA talks HTTP to your systems in three ways, and each has its own page section:

Call event webhooks

An agent forwards call.dialing, call.started, call.ended and call.recording to a URL you name.

Webhook schedules

Call a URL, or run an automation, at times decided by rules: weekdays, windows, intervals, dates.

Webhook logs

The record of every request around a call: dispatch, room, config fetch and each report the voice engine sent.

Everything below works with an API token whose role holds the matching permission: agents.update to configure an agent’s webhook, schedules.read / schedules.create / schedules.update / schedules.delete for schedules, webhook_logs.read for logs. See Authentication for tokens and roles.

export CALLVA_API="https://api.callva.io/api/v1/external"
export CALLVA_TOKEN="<your API token>"

Call event webhooks

A voice agent can forward the events of every call it handles to a URL of yours. You choose which of the four event types leave the platform; the rest are processed by CallVA as always and go nowhere else.

Event	When it fires
`call.dialing`	An outbound call starts ringing the other party. Sent once, however many rings follow. Inbound calls never send it.
`call.started`	The conversation begins: the outbound call is answered, or the inbound caller is joined.
`call.ended`	The call is over - answered, unanswered or failed - with its transcript and usage.
`call.recording`	The call’s recording is stored and ready to play. Arrives after `call.ended`.

Call event webhooks are produced for calls that run on CallVA’s own voice engine (the LiveKit worker), inbound and outbound.

How a call’s events travel

The voice worker reports each event to CallVA, signed with the project’s secret. CallVA verifies it, updates the call record (status, parties, timestamps, transcript, recording, billing), and only then forwards the report to your URL if the agent subscribes to that event type.

Configure the receiving URL

The URL lives on the agent. Three fields control it, set with Update an agent (PATCH /agents/{id}) or in the dashboard on the agent’s settings:

boolean

Turns forwarding on or off.

string

Where the events are posted. Any valid URL up to 2048 characters.

string[]

The event types to forward: any of call.dialing, call.started, call.ended, call.recording. The list you send replaces the stored one. An empty list forwards nothing, even with forwarding enabled and a URL set.

curl -X PATCH "$CALLVA_API/agents/01a1c749-5593-707d-877f-f89da2be547b" \
  -H "Authorization: Bearer $CALLVA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_webhook_enabled": true,
    "custom_webhook_url": "https://hooks.example.com/callva",
    "custom_webhook_events": ["call.ended", "call.started"]
  }'

Response (trimmed)

{
  "success": true,
  "message": "Agent updated successfully",
  "data": {
    "id": "01a1c749-5593-707d-877f-f89da2be547b",
    "name": "[TEST] docs-4d48b3d0 pipeline",
    "custom_webhook_enabled": true,
    "custom_webhook_url": "https://hooks.example.com/callva",
    "custom_webhook_events": ["call.started", "call.ended"],
    ...
  }
}

The stored list comes back de-duplicated and in the order a call meets the events. An unknown event name is refused with 422:

{
  "success": false,
  "message": "Validation failed",
  "errors": { "custom_webhook_events.0": ["The selected custom_webhook_events.0 is invalid."] }
}

Where to send, per call. An outbound call may name a different URL for itself in agent_overrides.custom_webhook_url; that call’s events go there. Which events leave is always read from the agent as it stands when each event arrives, so unsubscribing an event type stops it at once, even for calls already in progress.

Payloads

Each event is posted as a JSON object - the envelope the voice worker reported, with CallVA’s own credentials (signing secret, TURN password, LiveKit keys) removed and nothing else changed.

string

required

call.dialing, call.started, call.ended or call.recording.

string

required

Unique id of this report: <call id>:<event>:<milliseconds>.

number

required

When the report was built, Unix seconds with a fraction.

object

required

The call. id is the CallVA call id - use it with Get a call.

Show properties

string

CallVA call id.

string

outbound or inbound.

object

The party that placed the call: number, identity, name. On an outbound call this is your line.

object

The party that received the call, same shape. On an outbound call this is the person called.

number | null

Unix seconds when the conversation started.

number | null

Unix seconds when it ended.

number | null

Seconds between start and end.

string

dialing on call.dialing, in_progress on call.started. On call.ended the outcome: completed, no_answer, rejected, canceled or failed.

string | null

Who ended the call: agent, user, silence, duration or no_answer.

string | null

Why a call nobody joined never began.

number | null

The carrier’s SIP response code, when it refused the dial.

string | null

The carrier’s SIP response phrase.

string

CallVA project id.

string

CallVA organization id.

object

The agent configuration the call ran with, including any per-call override: id, name, prompt, greeting and timeout settings, custom_webhook_enabled, custom_webhook_url.

string | null

Which CallVA deployment served the call.

object

What the voice engine reported, verbatim: room, job, participant, sip (SIP attributes such as callStatus) and disconnect_reason. On call.ended it also carries session_report, with chat_history.items (the raw conversation) and usage (per-provider usage). Not present on call.recording.

object | null

On call.ended, where the recording will be stored: delivery, audio_key, session_report_key. On call.recording, the same with stored: true. Keys are object names, never URLs; play the audio through Stream a call’s recording.

array | null

What went wrong during the call, when anything did.

object | null

Session tags and outcome the agent recorded: tags, outcome, reason.

call.dialing
call.started
call.ended
call.recording

{
  "event": "call.dialing",
  "id": "01a1c74e-54f2-73f6-8af6-3ef541efe3a0:call.dialing:1789000000000",
  "timestamp": 1789000000.0,
  "call": {
    "id": "01a1c74e-54f2-73f6-8af6-3ef541efe3a0",
    "direction": "outbound",
    "from": { "number": "+15555550199", "identity": null, "name": null },
    "to": { "number": "+15555550100", "identity": "sip_+15555550100", "name": null },
    "started_at": null,
    "ended_at": null,
    "duration": null,
    "status": "dialing",
    "ended_by": null,
    "reason": null,
    "sip_status_code": null,
    "sip_status": null,
    "project_id": "01a1c749-5525-731a-ab9f-61ffbf9e4ef2",
    "tenant_id": "01a1c749-5387-7002-8154-5a7913629e6e",
    "type": "sip"
  },
  "agent": {
    "id": "01a1c749-5593-707d-877f-f89da2be547b",
    "name": "Reminder agent",
    "custom_webhook_enabled": true,
    "custom_webhook_url": "https://hooks.example.com/callva",
    ...
  },
  "environment": "production",
  "livekit": {
    "room": { "name": "...", "sid": "...", "metadata": null },
    "job": { ... },
    "participant": { "identity": "sip_+15555550100", ... },
    "sip": { "callStatus": "dialing", ... }
  },
  "recording": null,
  "errors": null,
  "tags": null
}

{
  "event": "call.started",
  "id": "01a1c74e-54f2-73f6-8af6-3ef541efe3a0:call.started:1789000004500",
  "timestamp": 1789000004.5,
  "call": {
    "id": "01a1c74e-54f2-73f6-8af6-3ef541efe3a0",
    "direction": "outbound",
    "from": { "number": "+15555550199", "identity": null, "name": null },
    "to": { "number": "+15555550100", "identity": "sip_+15555550100", "name": null },
    "started_at": 1789000004.5,
    "ended_at": null,
    "duration": null,
    "status": "in_progress",
    "ended_by": null,
    ...
  },
  "agent": { "id": "01a1c749-5593-707d-877f-f89da2be547b", ... },
  "environment": "production",
  "livekit": { "room": { ... }, "job": { ... }, "participant": { ... }, "sip": { ... } },
  "recording": null,
  "errors": null,
  "tags": null
}

{
  "event": "call.ended",
  "id": "01a1c74e-54f2-73f6-8af6-3ef541efe3a0:call.ended:1789000046500",
  "timestamp": 1789000046.5,
  "call": {
    "id": "01a1c74e-54f2-73f6-8af6-3ef541efe3a0",
    "direction": "outbound",
    "from": { "number": "+15555550199", "identity": null, "name": null },
    "to": { "number": "+15555550100", "identity": "sip_+15555550100", "name": null },
    "started_at": 1789000004.5,
    "ended_at": 1789000046.5,
    "duration": 42.0,
    "status": "completed",
    "ended_by": "user",
    "reason": null,
    "sip_status_code": null,
    "sip_status": null,
    ...
  },
  "agent": { "id": "01a1c749-5593-707d-877f-f89da2be547b", ... },
  "environment": "production",
  "livekit": {
    "room": { ... },
    "job": { ... },
    "participant": { ... },
    "sip": { ... },
    "disconnect_reason": "CLIENT_INITIATED",
    "session_report": {
      "chat_history": {
        "items": [
          { "type": "message", "role": "assistant", "content": ["Hello, this is a reminder call."], "created_at": 1789000005.1 },
          { "type": "message", "role": "user", "content": ["Hi, thanks."], "created_at": 1789000009.8 }
        ]
      },
      "usage": [ ... ]
    }
  },
  "recording": {
    "delivery": "storage",
    "audio_key": "01a1c74e-54f2-73f6-8af6-3ef541efe3a0.ogg",
    "session_report_key": "01a1c74e-54f2-73f6-8af6-3ef541efe3a0.session.json"
  },
  "errors": null,
  "tags": null
}

{
  "event": "call.recording",
  "id": "01a1c74e-54f2-73f6-8af6-3ef541efe3a0:call.recording:1789000048000",
  "timestamp": 1789000048.0,
  "call": { "id": "01a1c74e-54f2-73f6-8af6-3ef541efe3a0", ... },
  "agent": { "id": "01a1c749-5593-707d-877f-f89da2be547b", ... },
  "environment": "production",
  "recording": {
    "delivery": "storage",
    "audio_key": "01a1c74e-54f2-73f6-8af6-3ef541efe3a0.ogg",
    "session_report_key": "01a1c74e-54f2-73f6-8af6-3ef541efe3a0.session.json",
    "stored": true
  },
  "tags": null
}

call.recording is thin on purpose: no livekit block, no transcript, no usage. All of that arrived with call.ended under the same call id.

The transcript CallVA stores is built from livekit.session_report.chat_history, with consecutive pieces of one speaker merged into utterances. If you want the stored version rather than the raw one, read it with Get a call’s transcript.

Delivery: headers, timeout, retries


Method	`POST`, body is the JSON envelope
Headers	`Content-Type: application/json`. No signature header.
Timeout	5 seconds
Retries	None. One attempt per event.
Your answer	Read by nobody: any status counts as delivered. Answer `2xx` quickly and do slow work after responding.
Ordering	Sent as CallVA processes each report, so normally `dialing`, `started`, `ended`, `recording`.
Logged	Not in webhook logs; the report that triggered it is.

The forwarded request is not signed, so treat its body as a notification, not as proof. Use an HTTPS URL that is hard to guess (for example with a long random path segment), and before you act on an event, confirm it by reading the call with Get a call. Deduplicate on the envelope id: if CallVA fails while processing a report, the worker retries that report and your URL can see the same id twice.

The project’s webhook signing secret

Every project has a signing secret of its own (the agent_webhook_secret project setting). It authenticates the reports a voice worker sends to CallVA - the signed arrows in the diagram above - and only that project’s secret verifies that project’s calls. CallVA’s own worker receives the secret with each call’s configuration, so you need it only if you run your own LiveKit worker against CallVA, or relay reports to CallVA yourself. The worker signs each report like this:

POST /api/v1/webhooks/livekit
Content-Type: application/json
X-Webhook-Timestamp: 1789000046
X-Webhook-Signature: sha256=<hex HMAC-SHA256 of "{timestamp}.{raw body}" keyed with the secret>
X-Webhook-Idempotency-Key: <unique per report; a repeat returns the first answer>

CallVA recomputes the HMAC over the exact raw body, compares in constant time, and refuses with 401 when a header is missing (missing_signature), the timestamp is more than 300 seconds from its clock (timestamp_expired), the signature does not start with sha256= (invalid_signature_format), the call is unknown (unknown_call), or the HMAC differs (invalid_signature). The same check, in code:

import crypto from "node:crypto";

const MAX_DRIFT_SECONDS = 300;

// Sign a raw JSON body the way CallVA expects.
export function sign(secret, rawBody, timestamp = Math.floor(Date.now() / 1000)) {
  const hex = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  return { "X-Webhook-Timestamp": String(timestamp), "X-Webhook-Signature": `sha256=${hex}` };
}

// Verify a request: rawBody must be the exact bytes received, not re-serialized JSON.
export function verify(secret, rawBody, timestampHeader, signatureHeader) {
  if (!timestampHeader || !signatureHeader) return false;
  const ts = Number(timestampHeader);
  if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > MAX_DRIFT_SECONDS) return false;
  if (!signatureHeader.startsWith("sha256=")) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestampHeader}.${rawBody}`)
    .digest("hex");
  const given = signatureHeader.slice(7);
  return given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

import hashlib
import hmac
import time

MAX_DRIFT_SECONDS = 300


def sign(secret: str, raw_body: bytes, timestamp: int | None = None) -> dict[str, str]:
    """Headers for a raw JSON body, signed the way CallVA expects."""
    ts = str(timestamp if timestamp is not None else int(time.time()))
    digest = hmac.new(secret.encode(), ts.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return {"X-Webhook-Timestamp": ts, "X-Webhook-Signature": f"sha256={digest}"}


def verify(secret: str, raw_body: bytes, timestamp_header: str | None, signature_header: str | None) -> bool:
    """raw_body must be the exact bytes received, not re-serialized JSON."""
    if not timestamp_header or not signature_header:
        return False
    try:
        ts = int(timestamp_header)
    except ValueError:
        return False
    if abs(time.time() - ts) > MAX_DRIFT_SECONDS:
        return False
    if not signature_header.startswith("sha256="):
        return False
    expected = hmac.new(secret.encode(), timestamp_header.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature_header[7:], expected)

To replace the secret, call Rotate the webhook signing secret. The old secret stops verifying at once, so reports from calls already running with it are refused. The answer confirms has_value and never contains the secret:

curl -X POST "$CALLVA_API/settings/project/agent-webhook-secret/generate" \
  -H "Authorization: Bearer $CALLVA_TOKEN" \
  -H "Accept: application/json"

Response (trimmed)

{
  "success": true,
  "message": "Webhook signing secret generated",
  "data": {
    "key": "agent_webhook_secret",
    "label": "Agent Webhook Secret",
    "scope": "project",
    "is_secret": true,
    "has_value": true,
    "value": null,
    ...
  }
}

Read the value with Reveal a project setting, which needs the project_secrets.read permission. Generating needs settings.update.

Webhook schedules

A webhook schedule calls one URL - or runs one automation - at the moments its rules allow. Use it for a nightly sync, a report every weekday morning, a heartbeat every five minutes inside office hours.

The model

A schedule is the target and how to call it: webhook_url, webhook_method (GET, POST, PUT, PATCH, DELETE), webhook_headers, webhook_payload, timeout_seconds (1-300, default 30), max_retries (0-10, default 3), retry_delay_seconds (0-3600, default 60) and is_active. With target_type: "automation" and an automation_id, it runs that automation instead of calling a URL. A rule says when. Each rule has a priority (lower runs first), an action (run or skip), and conditions that must all pass:

Condition	Fields	Passes when
Date	`date_from`, `date_to`	Unset: always. Only `date_from`: that day. Both: any day in the range, inclusive.
Weekday	`days_of_week`	Empty: always. Otherwise the day is listed, `0` = Sunday … `6` = Saturday.
Time window	`time_from`, `time_to` (`HH:mm` or `HH:mm:ss`)	Unset: always. A window whose end is before its start runs overnight.

execution_interval (seconds, default 60, at least 10 for run rules, at most 86400) sets the cadence inside a matching window. Times are anchored to time_from (or midnight): an interval of 300 from 09:00 fires at 09:00, 09:05, 09:10 and so on, with time_to inclusive. Rules are evaluated in priority order and the first rule whose conditions all pass wins. When no rule matches, nothing runs. A rule with is_exclusive: true and a date “owns” its dates: on those days no lower-priority rule is consulted, and outside its own time window the answer is skip. Use it for holidays and one-off days. Rules are evaluated in the schedule’s timezone: the project’s timezone setting, else the organization’s, else UTC.

Pre-schedule, then execute

A scheduler ticks every ten seconds and does three things in order. An execution moves through these states:

One run per moment. A schedule and a run time identify an execution uniquely, so overlapping ticks cannot create or send the same run twice.
No replay after an outage. If the scheduler was down and several runs of a schedule are due at once, only the newest is sent; the older ones are marked skipped with Skipped: newer execution available (heartbeat gap recovery).
Deactivating cancels planned runs. Executions already pre-scheduled re-check the schedule and rule when they come due and are marked skipped if either was switched off (Schedule was deactivated before execution), without any request.
max_retries: 0 means one attempt. Connection errors, timeouts and non-2xx answers all count as failures.
What is sent. POST, PUT and PATCH send webhook_payload as JSON (with Content-Type: application/json unless your headers set one); GET and DELETE send no body. Your webhook_headers are sent as given. Scheduled requests are not signed: put a credential for your endpoint in webhook_headers.
Automation targets run the automation with no arguments, so every parameter of its main needs a default.

Create a schedule

Create a webhook schedule:

curl -X POST "$CALLVA_API/webhook-schedule" \
  -H "Authorization: Bearer $CALLVA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Docs heartbeat",
    "description": "Pings the receiver every five minutes on weekdays",
    "target_type": "webhook",
    "webhook_url": "https://hooks.example.com/heartbeat",
    "webhook_method": "POST",
    "webhook_headers": {"X-Source": "callva-schedule"},
    "webhook_payload": {"job": "sync"},
    "max_retries": 2,
    "retry_delay_seconds": 60,
    "timeout_seconds": 10,
    "rules": [
      {"name": "Weekdays, every 5 minutes", "priority": 10, "action": "run", "days_of_week": [1,2,3,4,5], "execution_interval": 300},
      {"name": "Skip New Year", "priority": 1, "action": "skip", "date_from": "2027-01-01", "date_to": "2027-01-01", "is_exclusive": true}
    ]
  }'

Response 201 (trimmed)

{
  "success": true,
  "message": "Webhook schedule created successfully",
  "data": {
    "id": "01a1c74e-cfb3-7032-bad6-ffa6090fcc15",
    "project_id": "01a1c749-5525-731a-ab9f-61ffbf9e4ef2",
    "name": "Docs heartbeat",
    "target_type": "webhook",
    "automation_id": null,
    "webhook_url": "https://hooks.example.com/heartbeat",
    "webhook_method": "POST",
    "webhook_headers": {"X-Source": "callva-schedule"},
    "webhook_payload": {"job": "sync"},
    "is_active": true,
    "max_retries": 2,
    "retry_delay_seconds": 60,
    "timeout_seconds": 10,
    "rules": [
      {
        "id": "01a1c74e-cfbc-72f5-8701-63ee4505d522",
        "name": "Skip New Year",
        "priority": 1,
        "date_from": "2027-01-01T00:00:00.000000Z",
        "date_to": "2027-01-01T00:00:00.000000Z",
        "days_of_week": null,
        "time_from": null,
        "time_to": null,
        "action": "skip",
        "execution_interval": null,
        "is_exclusive": true,
        "is_active": true
      },
      {
        "id": "01a1c74e-cfba-7121-bd78-57643f0d99ec",
        "name": "Weekdays, every 5 minutes",
        "priority": 10,
        "days_of_week": [1, 2, 3, 4, 5],
        "time_from": null,
        "time_to": null,
        "action": "run",
        "execution_interval": 300,
        "is_exclusive": false,
        "is_active": true,
        ...
      }
    ],
    ...
  }
}

Always send webhook_headers and webhook_payload, as {} when you have none. Leaving either out is answered with a 500 (Not null violation) and nothing is created.

Schedule names are unique within a project. Header values are stored as given and returned to anyone who can read the schedule, so give schedules.read only to roles that may see the credentials you put there.

Preview a moment

Preview a webhook schedule tells you which rule governs a moment and whether it runs. It checks the rule conditions, not interval alignment: a moment between two interval ticks still reports run if a run rule matches.

curl -X POST "$CALLVA_API/webhook-schedule/01a1c74e-cfb3-7032-bad6-ffa6090fcc15/preview" \
  -H "Authorization: Bearer $CALLVA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"datetime": "2026-11-11T09:00:00Z"}'

{
  "success": true,
  "message": "Schedule preview generated successfully",
  "data": {
    "datetime": "2026-11-11T09:00:00+00:00",
    "datetime_in_schedule_tz": "2026-11-11T09:00:00+00:00",
    "timezone": "UTC",
    "matched": true,
    "rule": {
      "id": "01a1c74e-cfba-7121-bd78-57643f0d99ec",
      "name": "Weekdays, every 5 minutes",
      "priority": 10,
      "action": "run",
      "is_exclusive": false
    },
    "action": "run",
    "exclusive_block": false
  }
}

{
  "success": true,
  "message": "Schedule preview generated successfully",
  "data": {
    "datetime": "2026-11-15T09:00:00+00:00",
    "datetime_in_schedule_tz": "2026-11-15T09:00:00+00:00",
    "timezone": "UTC",
    "matched": false,
    "rule": null,
    "action": "skip",
    "exclusive_block": false
  }
}

{
  "success": true,
  "message": "Schedule preview generated successfully",
  "data": {
    "datetime": "2027-01-01T09:00:00+00:00",
    "datetime_in_schedule_tz": "2027-01-01T09:00:00+00:00",
    "timezone": "UTC",
    "matched": true,
    "rule": {
      "id": "01a1c74e-cfbc-72f5-8701-63ee4505d522",
      "name": "Skip New Year",
      "priority": 1,
      "action": "skip",
      "is_exclusive": true
    },
    "action": "skip",
    "exclusive_block": false
  }
}

exclusive_block: true means an exclusive rule owns the date but the moment is outside its time window, so the answer is skip and no other rule was asked.

Read the execution history

List a schedule’s executions lists executions, upcoming (pre-scheduled) ones included. It is ordered by triggered_at descending, so runs not yet triggered come first. per_page defaults to 50.

curl "$CALLVA_API/webhook-schedule/01a1c74e-cfb3-7032-bad6-ffa6090fcc15/execution?per_page=5" \
  -H "Authorization: Bearer $CALLVA_TOKEN" \
  -H "Accept: application/json"

Response (trimmed)

{
  "success": true,
  "message": "Webhook executions retrieved successfully",
  "data": [
    {
      "id": "01a1c74e-eacb-70e1-b5f5-c98c3629b30d",
      "schedule_id": "01a1c74e-cfb3-7032-bad6-ffa6090fcc15",
      "scheduled_at": "2026-11-10T21:20:00.000000Z",
      "triggered_at": null,
      "matched_rule_id": "01a1c74e-cfba-7121-bd78-57643f0d99ec",
      "matched_rule_name": "Weekdays, every 5 minutes",
      "action_taken": "run",
      "status": "scheduled",
      "request_url": "https://hooks.example.com/heartbeat",
      "request_method": null,
      "response_status_code": null,
      "attempt_number": 0,
      "next_retry_at": null,
      ...
    },
    {
      "id": "01a1c74e-eac5-72b7-bf8d-03daf533a946",
      "schedule_id": "01a1c74e-cfb3-7032-bad6-ffa6090fcc15",
      "scheduled_at": "2026-11-10T21:15:00.000000Z",
      "triggered_at": "2026-11-10T21:15:00.000000Z",
      "matched_rule_id": "01a1c74e-cfba-7121-bd78-57643f0d99ec",
      "matched_rule_name": "Weekdays, every 5 minutes",
      "action_taken": "run",
      "status": "success",
      "request_url": "https://hooks.example.com/heartbeat",
      "request_method": "POST",
      "request_headers": {"X-Source": "callva-schedule", "Content-Type": "application/json"},
      "request_payload": {"job": "sync"},
      "response_status_code": 204,
      "response_body": "",
      "response_time_ms": 18,
      "error_message": null,
      "attempt_number": 0,
      "next_retry_at": null,
      ...
    }
  ],
  "pagination": {"current_page": 1, "last_page": 1, "per_page": 5, "total": 3, "from": 1, "to": 3},
  "meta": {"project_id": "01a1c749-5525-731a-ab9f-61ffbf9e4ef2"}
}

Executions keep the request and response bodies they carried. Finished ones (success, failed, skipped) are deleted once older than the organization’s webhook_execution_retention_days setting: 30 days by default, between 7 and 90. An execution that stays in processing means the worker stopped mid-call; nothing reclaims it.

Update, pause and delete

Update a webhook schedule is a full replacement: send every field you want to keep. Omitted settings return to their defaults (max_retries 3, timeout_seconds 30, is_active true), and omitted rules are deleted. Send a rule’s id to keep and update it; a rule without an id is created.

curl -X PUT "$CALLVA_API/webhook-schedule/01a1c74e-cfb3-7032-bad6-ffa6090fcc15" \
  -H "Authorization: Bearer $CALLVA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Docs heartbeat",
    "target_type": "webhook",
    "webhook_url": "https://hooks.example.com/heartbeat",
    "webhook_method": "POST",
    "webhook_headers": {"X-Source": "callva-schedule"},
    "webhook_payload": {"job": "sync"},
    "is_active": false,
    "rules": [
      {"id": "01a1c74e-cfba-7121-bd78-57643f0d99ec", "name": "Weekdays, every 5 minutes", "priority": 10, "action": "run", "days_of_week": [1,2,3,4,5], "execution_interval": 300}
    ]
  }'

Response (trimmed)

{
  "success": true,
  "message": "Webhook schedule updated successfully",
  "data": {
    "id": "01a1c74e-cfb3-7032-bad6-ffa6090fcc15",
    "is_active": false,
    "max_retries": 3,
    "timeout_seconds": 30,
    "rules": [ { "id": "01a1c74e-cfba-7121-bd78-57643f0d99ec", "name": "Weekdays, every 5 minutes", ... } ],
    ...
  }
}

Setting is_active: false pauses the schedule: no new runs are pre-scheduled, and runs already planned are marked skipped when they come due. Delete a schedule removes it with its rules and execution history:

curl -X DELETE "$CALLVA_API/webhook-schedule/01a1c74e-cfb3-7032-bad6-ffa6090fcc15" \
  -H "Authorization: Bearer $CALLVA_TOKEN" \
  -H "Accept: application/json"

{ "success": true, "message": "Webhook schedule deleted successfully" }

List all schedules (per_page defaults to 15) and get one return schedules with their rules in priority order.

Webhook logs

Webhook logs are a project’s record of the HTTP exchanges around its calls, kept for debugging. Each entry stores the full request (method, URL, headers with credentials redacted, payload, source IP), the response (status, body, time taken), a processing status, an error message, and the call it relates to. Entries come from these exchanges:

`type`	`event_type`	What was recorded
`call`	`dispatch-request`	An outbound call request you sent, including refused ones.
`call`	`room-create`, `agent-dispatch`, `participant-create`	Each step CallVA took with the voice engine to place an outbound call.
`call`	`call.dialing`, `call.started`, `call.ended`, `call.recording`	Each report the voice worker sent CallVA about a call, as received.
`config_request`	`config-request-webrtc`, `config-request-sip`, `config-request-livekit`	The voice worker asking for an agent’s configuration at the start of a call.
`config_request`	`config-override`	CallVA calling the agent’s custom config URL for a call, with what it answered.

processing_status is success, validation_failed, processing_error or signature_invalid. Forwards to your custom webhook URL and scheduled webhook requests are not webhook-log entries; the latter have their own execution history.

List and filter

List webhook logs, newest first:

curl "$CALLVA_API/webhook-logs?processing_status=validation_failed&event_type=dispatch-request&per_page=10" \
  -H "Authorization: Bearer $CALLVA_TOKEN" \
  -H "Accept: application/json"

Response (trimmed)

{
  "success": true,
  "message": "Webhook logs retrieved successfully",
  "data": [
    {
      "id": "01a1c74e-6218-7367-9c7d-d705c5922bca",
      "tenant_id": "01a1c749-5387-7002-8154-5a7913629e6e",
      "project_id": "01a1c749-5525-731a-ab9f-61ffbf9e4ef2",
      "agent_id": null,
      "type": "call",
      "type_label": "Call",
      "event_type": "dispatch-request",
      "request_method": "POST",
      "request_url": "https://api.callva.io/api/v1/external/call",
      "request_headers": {
        "accept": ["application/json"],
        "content-type": ["application/json"],
        "authorization": ["[REDACTED]"],
        ...
      },
      "request_payload": {"agent_id": "01a1c749-5593-707d-877f-f89da2be547b"},
      "request_ip": "203.0.113.10",
      "response_status": 422,
      "response_body": {
        "error": "validation_error",
        "errors": {"destination": ["The destination field is required."]}
      },
      "response_time_ms": 346,
      "processing_status": "validation_failed",
      "processing_status_label": "Validation Failed",
      "error_message": "Validation failed: {\"destination\":[\"The destination field is required.\"]}",
      "logs": null,
      "related_call_id": null,
      "received_at": "2026-11-10T21:12:45.000000Z",
      "created_at": "2026-11-10T21:12:45.000000Z",
      "updated_at": "2026-11-10T21:12:45.000000Z",
      "agent": null
    }
  ],
  "pagination": {"current_page": 1, "last_page": 1, "per_page": 10, "total": 1, "from": 1, "to": 1}
}

Query parameter	Meaning
`search`	Text in the agent id, related call id, event type or error message.
`type`	`call` or `config_request`.
`event_type`	One event type, for example `call.ended`.
`processing_status`	`success`, `validation_failed`, `processing_error`, `signature_invalid`.
`agent_id`, `related_call_id`	Entries for one agent or one call.
`received_from`, `received_to`	Date range on `received_at`.
`response_status`, `response_time_min`, `response_time_max`	HTTP status, and response time in milliseconds.
`sort`	`received_at`, `created_at`, `type`, `event_type`, `processing_status`, `response_status` or `response_time_ms`; prefix `-` for descending. Default `-received_at`.
`page`, `per_page`	`per_page` defaults to 30, at most 100.

List webhook log filters returns the values to offer, including the event types that actually occur in this project:

curl "$CALLVA_API/webhook-logs/filters" \
  -H "Authorization: Bearer $CALLVA_TOKEN" \
  -H "Accept: application/json"

{
  "success": true,
  "message": "Filter options retrieved successfully",
  "data": {
    "types": [
      {"value": "call", "label": "Call"},
      {"value": "config_request", "label": "Config Request"}
    ],
    "processing_statuses": [
      {"value": "success", "label": "Success"},
      {"value": "validation_failed", "label": "Validation Failed"},
      {"value": "processing_error", "label": "Processing Error"},
      {"value": "signature_invalid", "label": "Signature Invalid"}
    ],
    "event_types": [
      {"value": "dispatch-request", "label": "Dispatch request"}
    ]
  }
}

One call’s logs

List a call’s webhook logs takes the same query parameters and answers 404 when the call is not in the project:

curl "$CALLVA_API/calls/01a1c74e-54f2-73f6-8af6-3ef541efe3a0/webhook-logs" \
  -H "Authorization: Bearer $CALLVA_TOKEN" \
  -H "Accept: application/json"

{
  "success": true,
  "message": "Webhook logs retrieved successfully",
  "data": [],
  "pagination": {"current_page": 1, "last_page": 1, "per_page": 30, "total": 0, "from": null, "to": null}
}

This call was created through the API rather than placed by the voice engine, so nothing was exchanged for it. For a placed call you see its dispatch steps, the configuration request and every lifecycle report, in order.

One entry

Get a webhook log returns one entry with the same fields, plus related_call when it names a call:

curl "$CALLVA_API/webhook-logs/01a1c74e-6218-7367-9c7d-d705c5922bca" \
  -H "Authorization: Bearer $CALLVA_TOKEN" \
  -H "Accept: application/json"

Response (trimmed)

{
  "success": true,
  "message": "Webhook log retrieved successfully",
  "data": {
    "id": "01a1c74e-6218-7367-9c7d-d705c5922bca",
    "type": "call",
    "event_type": "dispatch-request",
    "response_status": 422,
    "processing_status": "validation_failed",
    ...
  }
}

Request payloads can contain personal data such as phone numbers, and the log keeps them as received. Give webhook_logs.read only to roles that should see that. Entries are deleted once older than the organization’s webhook_log_retention_days setting: 30 days by default, between 7 and 90.

Automations

Point a call event webhook or a schedule at a script that runs inside CallVA.

Calls

The call record that events update and that webhook logs relate to.

Get started

Ways in

Guides

Call event webhooks

Webhook schedules

Webhook logs

Call event webhooks

How a call’s events travel

Configure the receiving URL

Payloads

Delivery: headers, timeout, retries

The project’s webhook signing secret

Webhook schedules

The model

Pre-schedule, then execute

Create a schedule

Preview a moment

Read the execution history

Update, pause and delete

Webhook logs

List and filter

One call’s logs

One entry

Automations

Calls

Call event webhooks

Webhook schedules

Webhook logs

​Call event webhooks

​How a call’s events travel

​Configure the receiving URL

​Payloads

​Delivery: headers, timeout, retries

​The project’s webhook signing secret

​Webhook schedules

​The model

​Pre-schedule, then execute

​Create a schedule

​Preview a moment

​Read the execution history

​Update, pause and delete

​Webhook logs

​List and filter

​One call’s logs

​One entry

​Related

Automations

Calls

Call event webhooks

How a call’s events travel

Configure the receiving URL

Payloads

Delivery: headers, timeout, retries

The project’s webhook signing secret

Webhook schedules

The model

Pre-schedule, then execute

Create a schedule

Preview a moment

Read the execution history

Update, pause and delete

Webhook logs

List and filter

One call’s logs

One entry

Related