Webhooks and billing

The gateway can tell your systems what happened on a call, and can hand you a durable billing record for every call. This chapter covers two separate feeds: lifecycle webhooks (call started, call ended, with the transcript) and billing records (one costed record per call, delivered with retries). It ends with the cost-rate file that prices those records.

Both feeds are plain JSON over HTTP POST to your endpoint. Settings go in .env; restart the gateway after changing them.

Lifecycle webhooks

Set WEBHOOK_URL to your endpoint to switch the feed on. Empty means off.

WEBHOOK_URL=https://hooks.example.com/voice
WEBHOOK_SECRET=change-me-long-random
WEBHOOK_AUTH_TOKEN=
LOG_LATENCY=false

The token goes out as <WEBHOOK_AUTH_HEADER>: <WEBHOOK_AUTH_SCHEME> <token>, so the defaults produce Authorization: Bearer <token>.

Delivery rules

• Delivery is fire and forget. There are no retries.
• A failure is logged as WARN: Lifecycle webhook [<event>] failed and never affects the call.
• At shutdown the gateway waits up to 10 seconds for pending deliveries.
• If you need guaranteed delivery with retries, use Billing records instead.

Events and headers

call.started payload

{
  "event": "call.started",
  "timestamp": "2026-10-24T09:15:02.114Z",
  "session": {
    "uuid": "5b1f0c1e-7a52-4d0e-9c43-2f7d1a9e6b10",
    "caller_id": "+9198xxxxxxxx",
    "caller_name": "Asha",
    "channel": "SIP/trunk-0001",
    "language_code": "ml-IN",
    "call_direction": "inbound",
    "mode": "pipeline",
    "bot_id": "default",
    "initiated_at": "2026-10-24T09:15:00.020Z",
    "answered_at": "2026-10-24T09:15:02.100Z"
  },
  "providers": {
    "llm": "litebot",
    "tts": "sarvam",
    "stt": "sarvam",
    "stt_actual": "sarvam"
  }
}

call_direction is inbound or outbound. mode is pipeline or realtime; in realtime mode providers holds a single realtime entry instead of llm, tts and stt.

call.ended payload

{
  "event": "call.ended",
  "timestamp": "2026-10-24T09:15:44.300Z",
  "session": {
    "uuid": "5b1f0c1e-7a52-4d0e-9c43-2f7d1a9e6b10",
    "caller_id": "+9198xxxxxxxx",
    "language_code": "ml-IN",
    "call_direction": "inbound",
    "mode": "pipeline",
    "bot_id": "default",
    "initiated_at": "2026-10-24T09:15:00.020Z",
    "answered_at": "2026-10-24T09:15:02.100Z",
    "duration_ms": 42000
  },
  "providers": { "llm": "litebot", "tts": "sarvam", "stt": "sarvam", "stt_actual": "sarvam" },
  "conversation": {
    "message_count": 4,
    "chat_history": [
      { "role": "assistant", "content": "Hello Asha, how can I help you today?" },
      { "role": "user", "content": "I want to book an appointment." }
    ]
  },
  "performance": {
    "session_start": "2026-10-24T09:15:02.100Z",
    "api_calls": 2,
    "avg_response_time": 1800
  },
  "hangup": {
    "hangup_reason": "bot_requested",
    "hangup_source": "bot",
    "hangup_at": "2026-10-24T09:15:44.200Z"
  },
  "metadata": { "campaign": "autumn" }
}

The blocks below appear in call.ended only when they apply.

Cost does not travel in the webhook. Per-call cost lives only in the billing record; the webhook carries performance.

Latency detail

LOG_LATENCY is off by default. Turn it on to get per-turn latency console lines, a performance CSV in the logs folder, and the performance.latency block above. See Operations for reading the logs.

Tool invocations

Set WEBHOOK_TOOL_DETAILS=true to add a tools list to call.ended. Each entry carries name, id, success, at, duration_ms, truncated and control.

Entries are merged by tool call id. Realtime LiteBot sends arguments but no result; the text pipeline sends the result but no arguments. A field the brain did not send is left out, never invented. See AI brain and Realtime mode.

Hosted customers do not set these variables; see Hosted customers.

Verifying the signature

When WEBHOOK_SECRET is set, every request carries X-Webhook-Signature: the lowercase hex HMAC-SHA256 of the raw request body, keyed with the secret. Compute it over the exact bytes received, before any JSON parsing, and compare in constant time.

raw      = read the request body as bytes
expected = hex( hmac_sha256( secret, raw ) )
sig      = request header "X-Webhook-Signature"
if not constant_time_equal( sig, expected ): reply 401 and stop
event    = parse_json( raw )
handle( event ) and reply 200

Billing records use the same procedure with BILLING_CDR_SECRET. A request without the header means the secret is not configured on the gateway side.

Billing records

Lifecycle webhooks are best effort. Billing records are not: the gateway writes one JSON record per finished call to disk first, then delivers it with retries. A record is never dropped; after the last attempt it moves to a dead-letter folder for you to inspect.

BILLING_CDR_ENABLED=true
BILLING_CDR_DIR=./cdr
BILLING_CDR_URL=https://billing.example.com/cdr
BILLING_CDR_SECRET=another-long-random

The feed is independent of WEBHOOK_URL. With the default BILLING_CDR_ENABLED=false the module does nothing.

Store layout

The /health response shows billing.pending and billing.dead. A dead count above zero is the one to alert on. See HTTP API.

Delivery and retries

The record is the JSON body, with no envelope. Headers:

Your endpoint must answer with a 2xx status to acknowledge. Anything else, 4xx included, schedules a retry. The wait between attempts is 1 minute, 5 minutes, 15 minutes, 1 hour, then 6 hours for each later attempt, up to BILLING_CDR_MAX_ATTEMPTS; on defaults that spans about 32 hours.

A record can legitimately arrive twice, for example when your endpoint processed it but the acknowledgement was lost. Deduplicate on X-Idempotency-Key.

Replaying records

After fixing your endpoint, move dead letters back with the replay call:

curl -X POST http://127.0.0.1:8081/billing/replay \
  -H "Content-Type: application/json" \
  -d '{"scope":"dead"}'

dead moves every dead letter back to pending with its attempt counter reset, then sweeps. pending forces an immediate sweep without waiting for the timer. The response reports how many were moved and the pending and dead counts. Details are in HTTP API.

Record fields

Records carry schema_version 2. A value of null means that stage never ran on the call, which is different from a zero. Costs are in rupees unless the field ends in _usd.

Reading the less obvious fields:

• Streaming speech recognition bills listening time, not speech, so stt_billed_seconds follows the time the call spent listening.
• tts_billed_chars and tts_cached_chars do not overlap: characters served from the TTS cache are counted separately and cost nothing. tts_spoken_chars is their sum.
• llm_total_tokens is always an integer or null.
• llm_source tells you how far to trust the AI cost. per-turn-usage, session-reconciled and realtime-usage are actual figures. flat-estimate and realtime-no-cost-event are estimates, and llm_cost_is_actual is false for them.

Cost tracking

Costs in the billing record come from the cost tracker, which prices each call from a rate table.

The built-in table holds list prices as of the release. They date quickly, so override them with your contract rates. No config/pricing.json ships; create it from the example below. Your file is merged over the built-in table, so it only needs the entries you change.

{
  "usdInr": 87,
  "stt": {
    "sarvam": 30
  },
  "tts": {
    "google": 2.61,
    "smallest": 1.5225
  },
  "llm_models": {
    "gemini-2.5-flash": {
      "text_input": 0.3,
      "text_output": 2.5,
      "cached_input": 0.075,
      "audio_input": 1.0
    }
  }
}

The numbers above are examples, not current prices.

How rates are looked up

For speech synthesis the tracker tries the most specific key first, then the bare provider name.

Speech recognition keys are the bare provider names: sarvam, groq, openai, deepgram, google, gemini and vexyl-stt.

An AI model with no entry in llm_models produces null rates in the record, not zero. Add every model your brain bills, using the model id without any models/ prefix.

Hosted customers

On the hosted service Vexyl sets the webhook URL and secret for you; see Hosted. Billing records are not exposed to hosted customers.