Skip to content
Comcent Comcent Comcent Documentation

Webhooks and vCon

Webhooks send each finished call to your own system, so you can store it in a CRM, a data warehouse or a ticketing tool. The call is delivered as a vCon document, an open JSON format for conversations.

Create a webhook

Section titled “Create a webhook”
  1. As an admin, open Settings → Webhooks and add a webhook.
  2. Enter a Name (a friendly name, at least 3 characters) and the URL of your endpoint (http:// or https://; use HTTPS in production).
  3. Tick at least one event (Call Update Event, Presence Update Event) and save.
  4. Copy the webhook’s Auth Token from the list. Comcent sends it with every delivery so your endpoint can verify the request.

Deliveries

Section titled “Deliveries”

Comcent currently delivers one event type, NEW_CALL_STORY, to every webhook of the organisation. It is sent once the call has been processed, after the transcript and analysis are ready when AI Insights are on.

POST /your/endpoint HTTP/1.1
Content-Type: application/json
X-Api-Token: <the webhook's auth token>


{
  "type": "NEW_CALL_STORY",
  "data": { …vCon document… }
}
  • Verify the token. Reject requests whose X-Api-Token header does not match the token shown in Comcent.
  • Respond quickly with a 2xx status and do slow work in the background.
  • Deliveries are attempted once; failures are logged on the Comcent server but not retried. If you need every call, also reconcile periodically with the REST API (call-stories).

The vCon document

Section titled “The vCon document”

data follows vCon version 0.4.0:

{
  "vcon": "0.4.0",
  "uuid": "<call story id>",
  "created_at": "2026-01-15T10:32:07Z",
  "parties": [
    { "tel": "+15551234567" },
    { "tel": "alice@acme.voice.example.com" }
  ],
  "dialog": [
    {
      "type": "recording",
      "start": "2026-01-15T10:32:09Z",
      "duration": 184,
      "parties": [0, 1],
      "mediatype": "audio/x-wav",
      "filename": "…",
      "url": "https://…",
      "content_hash": "sha512-…"
    }
  ],
  "attachments": [
    { "purpose": "comcent.call_story", "party": 0, "dialog": 0, "encoding": "json", "body": { … } }
  ],
  "analysis": [
    { "type": "transcript", "vendor": "comcent", "encoding": "json", "body": [ … ] },
    { "type": "sentiment", "vendor": "comcent", "encoding": "json", "body": [ … ] },
    { "type": "summary", "vendor": "comcent", "encoding": "none", "body": "…" }
  ]
}
SectionContents
partiesEveryone on the call. tel is a phone number or a member’s SIP address. dialog entries refer to parties by their index in this list.
dialogThe call’s audio. A recording entry per recorded leg, with a signed url to download the WAV file and a SHA-512 content_hash. When the call was transferred, transfer entries (with transferor, transferee, transfer_target, original and target_dialog) link one leg to the next. Calls that were never answered have an incomplete entry with a disposition such as no-answer or busy.
attachmentsOne attachment with purpose comcent.call_story: Comcent’s own call metadata, including every leg of the call.
analysisPresent when AI Insights ran: the transcript (a conversation, one entry per turn), sentiment (per party, with a score) and summary.