When a DID rings, the carrier’s inbound trunk routes the call into a LiveKit call-* room (per the dispatch rule created in carriers). LiveKit then fires a participant_joined webhook to CXB API, which picks a fleet worker and hands the call to CXB Core. The webhook handler lives in the API service’s LiveKit-webhook route.

​
Endpoint

POST /api/v1/livekit/webhook — no JWT/secret dependency; authenticated by the LiveKit webhook signature instead.
StepBehaviour
AuthAuthorization header (optionally Bearer -prefixed) verified by WebhookReceiver + TokenVerifier using livekit_api_key/secret. Missing → 401 Missing auth; bad signature → 401 Invalid signature.
Event filterIgnores any event other than participant_joined (returns {ok: true}).
Participant filterIgnores non-SIP participants (participant.kind != SIP).
Room filterIgnores rooms whose name does not start with call-.

​
Dispatch flow

Attribute extraction helpers:
FieldSource
caller_numbersip.phoneNumber attribute, else parsed from sip_/sip- identity
dialed_numbersip.calledNumber, else sip.trunkPhoneNumber
trunk_idsip.trunkID
call_idsip.callID
If dialed_number is empty but trunk_id is known, CXB API looks up the carrier by lk_inbound_trunk_id and uses the first DID’s number as a fallback.

​
Fleet handoff

  • core_fleet is read from system_settings; empty → 503 No fleet.
  • pick_fleet_server selects the healthiest host; none healthy → 503 No healthy fleet.
  • Dispatch payload: {room_name, caller_number, dialed_number, call_id} to POST {fleet}/livekit/dispatch with X-CXB-Core-Secret and a 10s timeout.
  • A 200 relays CXB Core’s JSON; non-200 returns the fleet status + body; transport errors return 502.
This route uses the same pick_fleet_server as dialout but a tighter 10s timeout. Per the deployment notes, the /livekit/dispatch 429 retry policy must not be enabled at the ingress unless CXB Core changes first, because CXB Core’s 429 path removes the inbound SIP participant.

Carriers & trunks

Inbound trunk + dispatch rule that produce call-* rooms.

Fleet routing

Health checks and best-server selection.

LiveKit SIP inbound (CXB Core)

What CXB Core’s /livekit/dispatch does with the call.

SIP dialout

The outbound counterpart.