Events and webhooks

One event shape serves the socket and the webhook. On the plain WebSocket protocol you receive every event as a JSON text frame. On Twilio and Telnyx streams you receive events on the webhook only.

Common fields

Field	Meaning
`type`	Event type. See below.
`session_id`	The session. Use it with Get one session.
`kind`	`filter` or `honeypot`.
`call_id`	Your `call_id`, the Twilio CallSid, the Telnyx call control id, or the SIP Call-ID.
`from`, `to`	E.164 numbers when known.
`at`	RFC 3339 time.

Event types

`type`	When	Extra fields	Socket	Webhook
`session.started`	The start message was accepted.	`persona` (honeypot only)	yes	yes
`transcript.line`	One utterance is final.	`speaker`, `text`	yes	no
`verdict`	The score or category changed enough to matter.	`verdict`	yes	yes
`session.error`	Honeypot only. Speech synthesis failed.	`error`, `text`	yes	yes
`session.ended`	The call ended and the final analysis is done.	`verdict`, `intel`, `transcript`, `duration_seconds`, `reported`, `reported_numbers`	yes	yes

speaker is caller, callee, or the persona's name.

session.error ends a honeypot session when the greeting could not be spoken. In every other case it is advisory and the session continues. The filter never sends it.

When a verdict event is sent

The filter scores the caller's text after every final utterance with the rule engine. It also runs the model every 30 seconds when at least 120 new characters arrived. A verdict event is sent when:

The first score reaches 0.3 or more.

The level changes.

The category changes.

The score moves by 0.15 or more.

A rules-only score below 0.5 is never sent. A rules-only score never lowers a score the model produced. Expect zero events on a clean call and two to five on a scam call.

Examples

verdict:

{
  "type": "verdict",
  "session_id": "7463336c-c965-450f-b188-e6908e969395",
  "kind": "filter",
  "call_id": "your-call-id",
  "from": "+15559990000",
  "to": "+15551234567",
  "at": "2026-09-13T15:04:11Z",
  "verdict": {
    "score": 0.72,
    "level": "likely_scam",
    "category": "Advance Fee Loan",
    "tactics": ["untraceable_payment", "urgency"],
    "signals": ["pitches a loan", "asks for money before a loan"],
    "source": "heuristic"
  }
}

session.ended:

{
  "type": "session.ended",
  "session_id": "7463336c-c965-450f-b188-e6908e969395",
  "kind": "filter",
  "call_id": "your-call-id",
  "from": "+15559990000",
  "to": "+15551234567",
  "at": "2026-09-13T15:07:52Z",
  "verdict": {
    "score": 0.94,
    "level": "scam",
    "category": "Advance Fee Loan",
    "tactics": ["callback_pressure", "untraceable_payment", "urgency"],
    "signals": ["pay us up front, and then we would give you the loan", "send us a payment right now to +19998887766"],
    "summary": "Caller offers a $10,000 loan and demands an upfront payment to a phone number within the hour.",
    "source": "combined"
  },
  "intel": {
    "names": ["Dmitry"],
    "organizations": ["Bankloans.com"],
    "callback_numbers": ["+19998887766"],
    "amounts": ["$10,000"]
  },
  "transcript": "caller: Hi, this is Dmitry from Bankloans.com...\n",
  "duration_seconds": 221,
  "reported": true,
  "reported_numbers": 2
}

Webhook delivery

Set webhook to an HTTPS URL. HTTP URLs are ignored. The server posts every event except transcript.line.

Header	Value
`Content-Type`	`application/json`
`X-Voice-Event`	The event `type`.
`X-Voice-Signature`	`sha256=<hex>`. HMAC-SHA256 of the raw request body. The key is your API key.

Rules:

Answer with a 2xx status within 5 seconds. The server does not wait longer.

There is no retry. Store the session_id and read Get one session when a post is missing.

Events for one session may arrive out of order under load. Use at to order them.

Do not depend on a fixed source IP. Verify the signature instead.

Compute the HMAC over the raw bytes of the body, before any JSON parsing.

Verify the signature

Python:

Node.js:

The verdict object is described on Read a verdict.

Common fields#

Event types#

When a verdict event is sent#

Examples#