API basics
Webhook events
Every event a webhook subscription can receive, when it fires, and the fields in its payload.
This page is the catalogue. Receive webhooks covers subscribing, verifying the X-Webhook-Signature header, retries and the delivery log.
The envelope
Every delivery is one JSON object. Call events and chat events share the same envelope; a call event names the call, a chat event names the conversation.
{
"schema_version": "1.0",
"event": "call.ended",
"event_id": "evt_5c0e8a1f2b3d4e6f8a9b0c1d2e3f4a5b",
"idempotency_key": "call_7f2e...:call.ended:evt_5c0e...",
"call_id": "call_7f2e9a0b1c2d4e5f8a6b7c8d9e0f1a2b",
"timestamp": "2026-10-28T09:42:11.204Z",
"identity": {
"org_id": "org_...",
"project_id": "proj_...",
"assistant_id": "asst_...",
"assistant_version": 4
},
"metadata": { "crm_id": "0061x00000AbCdE" },
"data": { "call_type": "outbound", "ended_reason": "call.ending.agent-ended-call", "duration_ms": 182340 }
}{
"schema_version": "1.0",
"event": "lead.captured",
"event_id": "evt_9d1f...",
"idempotency_key": "conv_0c8e...:lead.captured:evt_9d1f...",
"conversation_id": "conv_0c8e5f2a9b7d4c1e86f3a0d2b4c6e8f1",
"timestamp": "2026-10-28T09:31:04.517Z",
"identity": { "org_id": "org_...", "project_id": "proj_...", "assistant_id": "asst_..." },
"data": { "...": "per event, below" }
}| Field | Meaning |
|---|---|
event | The event type. |
event_id | Unique per event and the same on every redelivery of it. Store it and skip events you have already handled. |
idempotency_key | <call_id or conversation_id>:<event>:<event_id>, if you prefer one string to dedupe on. |
timestamp | When the event happened, ISO 8601 in UTC. Deliveries can arrive out of order; sort by this, not by arrival. |
identity | The organization, project and assistant it belongs to. Call events add assistant_version. |
metadata | Call events only: the metadata you passed when you started the call, echoed back. |
livemode | false on events from sandbox chats and sandbox calls, which reach only subscriptions with mode: "test" (sandbox subscriptions). livemode: false means sandbox. Live events have no livemode field. |
data | The event's own fields. |
Call events can also carry room_name and server_region; treat both as diagnostics.
Call events
| Event | Fires when |
|---|---|
call.started | The assistant has joined the call and loaded its configuration. |
call.connected | The other person is on the line. For an outbound call, after they answer. |
call.ended | The call is over, with its transcript, usage and recordings. |
call.started and call.connected carry caller_number and called_number when known.
call.ended carries:
| Field | Meaning |
|---|---|
call_type | inbound, outbound or web. |
ended_reason | Why it ended, as a phase-prefixed string such as call.ending.agent-ended-call, call.in-progress.customer-ended-call or call.start.customer-did-not-answer. New values appear over time. |
caller_number, called_number | The two ends of the call, when known. |
started_at, ended_at, duration_ms | Timing. duration_ms runs from connection to the end. |
messages | The transcript: role (user, assistant, tool), content, and for tool turns tool_calls and tool_call_id. Spoken turns carry seconds_from_start and duration_ms. |
usage | Billable usage rows: type plus token counts (input_tokens, output_tokens) or audio_duration seconds. |
recordings, recording_url | Recording references, when the call was recorded. Fetch playback links through GET/api/calls/{id}/recordings. |
performance | Latency figures. Treat the fields as diagnostics. |
For the full call, including the analysis that runs after it ends, read GET/api/calls/{id}.
Chat events
Chat events cover web chat and WhatsApp conversations.
| Event | Fires when | data |
|---|---|---|
conversation.started | A conversation is created. The website widget creates one with the visitor's first message; a WhatsApp conversation starts with the first inbound message. | visitor_id, parent_origin (the site it started on), widget_key_id. Each can be null. |
conversation.message.created | A message appears in the transcript: from the visitor, the assistant or a person on your team. | message (id, role of user, assistant or agent, content, seq, created_at, and agent and attachments when present; a turn spoken in a voice session adds channel voice and voice_session_id) and conversation (status, handoff_requested_at, taken_over). |
lead.captured | The assistant saved a lead, a later analysis created or refreshed it, the visitor sent files after it existed, or reading the chat after a voice session created or changed it. | lead (id, name, email, phone, fields, test, test_reason, traffic, and attachments when the visitor sent files), conversation_id, source (tool, analysis, attachments or voice), summary, and attribution when known: where the visitor came from (landing page, referrer, UTM tags), or only chat_page once they declined analytics. Every delivery is the whole lead as it is now: update in place. |
conversation.handoff_requested | The assistant asked for a person to take over. | reason, the last 20 transcript entries, visitor_id, lead_id. |
conversation.callback_requested | The visitor asked to be called back. | phone, and when given slot_start (the time they prefer), note, visitor_id, lead_id. |
conversation.takeover.started | A person took the conversation over. | agent (id, and email and name when known), source (console or api). |
conversation.takeover.released | The person handed it back, someone released their seat, the conversation ended, or their seat lapsed. | agent, reason (released, forced, conversation_ended or abandoned), and previous_holder when forced. |
conversation.analyzed | A background analysis of the conversation finished. | summary, structured, lead_id, through_seq, conversation_status, human_review, needs_review. |
conversation.ended | The conversation closed. | See below. |
conversation.analyzed can arrive more than once for one conversation, and out of order. Keep the one with the highest through_seq (the last message it read).
conversation.ended carries the outcome in one place:
| Field | Meaning |
|---|---|
status, ended_reason, message_count | How and why it closed, and its length. |
lead_id | The lead, if one was captured. |
handoff_status | none, pending, answered, missed (it ended before anyone took over) or abandoned (someone took over and left the visitor waiting). |
handoff_requested_at, handoff_answered_at, first_taken_over_at | Handoff timing. |
human_outcome, human_metrics | When a person took part: handled or abandoned, and their reply times. |
transcript | The whole conversation. Replies from a person read as assistant turns prefixed with [human agent] . |
usage | Model usage for the conversation. |
analysis | The latest analysis when it ended (summary, structured, through_seq, human_review), or null. A newer one can follow as conversation.analyzed. |
Attachments in any chat event are { id, name, content_type, size, url }. The url works without a key for up to seven days (less when the chat came from a sandbox key that is revoked or a preview link that is turned off), so copy the file if you need it longer.
Form events
form.submitted fires for every submission a form accepts, and for a held one when it is released. It is opt-in: a subscription receives it only when its events lists it by name. A test key's submission carries livemode: false and goes only to sandbox subscriptions.
{
"schema_version": "1.0",
"event": "form.submitted",
"event_id": "evt_2b4d...",
"idempotency_key": "fsub_8c1f...:form.submitted:evt_2b4d...",
"form_id": "form_4e7a1c9d2b3f4a5e8c6d0b1a2f3e4d5c",
"submission_id": "fsub_8c1f3a5e7b9d4c2e8a0f1b3d5e7a9c1e",
"timestamp": "2026-11-04T10:13:02.118Z",
"identity": { "org_id": "org_...", "project_id": "proj_..." },
"data": {
"form": { "id": "form_4e7a1c9d2b3f4a5e8c6d0b1a2f3e4d5c", "name": "Contact", "kind": "enquiry" },
"submission": {
"id": "fsub_8c1f3a5e7b9d4c2e8a0f1b3d5e7a9c1e",
"fields": { "name": "Ana Silva", "email": "ana@example.com", "cv": "ana-silva-cv.pdf" },
"page_url": "https://www.acmetravel.com/contact",
"referrer": "https://www.google.com/",
"utm": { "utm_source": "google", "utm_medium": "cpc" },
"click_ids": null,
"received_at": "2026-11-04T10:13:01.904Z",
"files": [
{ "id": "ffile_...", "field_key": "cv", "filename": "ana-silva-cv.pdf", "content_type": "application/pdf", "size_bytes": 182340, "scan_status": "pending", "url": "https://..." }
]
},
"lead_id": "lead_3a9c7e1f5b2d4c8e9f0a1b2c3d4e5f6a"
}
}| Field | Meaning |
|---|---|
form_id, submission_id | The form and the submission, also at the top level. There is no conversation_id, and identity has no assistant. |
data.form.kind | enquiry, callback, support, newsletter, careers or other. |
data.submission.fields | The fields as stored: trimmed, emails lowercased, a ticked consent as yes, a file field as its file names joined with ", ". |
data.submission.utm, click_ids | Attribution from the post, its page URL or the page context, or null. |
data.submission.files | The files sent with the submission: id, field_key, filename, content_type (read from the file's content), size_bytes, scan_status (pending, clean, infected, unscannable or not_scanned; see file uploads), and a url that works without a key for 7 days. With malware scanning on, a file is usually still pending when the event is sent: the url answers 409 file_scanning until the scan is clean (usually seconds) and 410 file_infected if it found malware. A replay signs each url again and sends the file's current scan_status. Copy a file if you need it longer. |
data.lead_id | The lead it made, or null: a newsletter or careers form, or a form with no field definition and no email or phone in the post. That lead's own lead.captured (schema 1.1, with form_id and form_submission_id) is sent too. |
data.form.channel | website, or google_lead_form for a Google lead form. After the other form keys. |
data.submission.ad | For a Google lead form, the ids Google sent (as attribution.ad_form in lead.captured); null for a website form. After the other submission keys. |
Lead follow-up events
Two opt-in events about leads someone should act on, from following up on leads. A subscription receives them only when its events lists them by name. Test leads are never nudged, so neither carries livemode, and neither carries an email or a phone: you have them from lead.captured, or read the lead.
lead.uncontacted fires once per lead, when a new lead is still uncontacted after the project's wait (60 minutes by default, counted in the project's contact hours when it has them):
{
"schema_version": "1.0",
"event": "lead.uncontacted",
"event_id": "evt_5c2e...",
"idempotency_key": "lead_3a9c...:lead.uncontacted",
"timestamp": "2026-11-04T10:35:00.000Z",
"identity": { "org_id": "org_...", "project_id": "proj_...", "assistant_id": null },
"data": {
"lead_id": "lead_3a9c7e1f5b2d4c8e9f0a1b2c3d4e5f6a",
"name": "Ana Ruiz",
"channel": "form",
"created_at": "2026-11-04T09:30:00.000Z",
"waiting_seconds": 3900,
"threshold_minutes": 60,
"counts_contact_hours": true,
"url": "https://console.brightshoal.com/leads/lead_3a9c7e1f5b2d4c8e9f0a1b2c3d4e5f6a"
}
}lead.follow_up_due fires when a lead's next_follow_up_at comes, once for each date set:
{
"schema_version": "1.0",
"event": "lead.follow_up_due",
"event_id": "evt_7a1d...",
"idempotency_key": "lead_3a9c...:lead.follow_up_due:2026-11-05T04:30:00.000Z",
"timestamp": "2026-11-05T04:30:20.000Z",
"identity": { "org_id": "org_...", "project_id": "proj_...", "assistant_id": null },
"data": {
"lead_id": "lead_3a9c7e1f5b2d4c8e9f0a1b2c3d4e5f6a",
"name": "Ana Ruiz",
"status": "contacted",
"next_follow_up_at": "2026-11-05T04:30:00.000Z",
"last_contacted_at": "2026-11-04T09:52:00.000Z",
"url": "https://console.brightshoal.com/leads/lead_3a9c7e1f5b2d4c8e9f0a1b2c3d4e5f6a"
}
}| Field | Meaning |
|---|---|
data.waiting_seconds | How long the lead had waited when the event was sent, wall clock. |
data.threshold_minutes | The project's wait. |
data.counts_contact_hours | The wait counted only the project's contact hours. |
data.url | The lead in the console, or null when the console address is not configured. |
A nudge more than 6 hours late (after an outage) is never sent.
Form health events
form.health.opened and form.health.resolved are opt-in. Opened fires when a form stops receiving the submissions it usually gets, starts refusing posts, fails to save them, or its form.submitted deliveries fail; it fires again, with the idempotency key ending :critical, when the problem turns critical. Resolved fires when it ends.
{
"schema_version": "1.0",
"event": "form.health.opened",
"event_id": "evt_9e3b...",
"idempotency_key": "fhinc_...:form.health.opened",
"timestamp": "2026-11-04T10:40:00.000Z",
"identity": { "org_id": "org_...", "project_id": "proj_..." },
"data": {
"incident_id": "fhinc_4c1e...",
"form": { "id": "form_4e7a...", "name": "Contact", "channel": "website" },
"rule": "form_refusing",
"severity": "warning",
"reason": "refused_site",
"title": "Contact is refusing posts from your site",
"detail": { "refused": 4, "posts": 5, "reason": "refused_site" },
"first_seen_at": "2026-11-04T10:12:00.000Z",
"last_seen_at": "2026-11-04T10:38:00.000Z",
"url": "https://console.brightshoal.com/channels/forms/form_4e7a..."
}
}| Field | Meaning |
|---|---|
data.rule | form_quiet (no submissions in a day when it usually gets them), form_refusing, form_failing (failing to save) or form_undelivered (form.submitted not reaching a webhook). |
data.severity | warning or critical. |
data.reason | For form_refusing, why posts are refused (such as refused_site, refused_fields, refused_paused); else null. |
data.title | The problem in words, as the console and Slack show it. |
data.detail | The rule's numbers. |
form.health.resolved has the same data plus resolved_at and resolution (recovered, quiet, manual or form_archived), with the idempotency key <incident_id>:form.health.resolved.
Choosing events
A subscription with an empty or missing events list receives every event type listed on this page in its mode. Event types added from now on are opt-in: a subscription receives one only when it lists it by name, so an endpoint never gets a payload it was not built for. A subscription's mode is set when you create it: live (the default) receives live traffic, test (sandbox) only sandbox chats and calls. Preview chats send no webhooks. List names to receive only those. A name that is not an event above is refused with 400 invalid_request, so a typo cannot leave a subscription silent.
lead.traffic is real, sandbox or test. Test leads (rule-caught leads from live chats) still produce lead.captured on live subscriptions, and lead.test is the effective test status. lead.test_reason is reserved_domain, business_domain, staging_site, or null. Delivery routing and the envelope's livemode follow chat mode, so a test lead has no livemode field and a sandbox lead has livemode: false. Use lead.traffic to keep test leads out of your CRM.
lead.captured schema 1.1
Leads from a chat are sent as schema_version 1.0, exactly as above. Leads from other channels (calls, forms) are sent as 1.1, and chat leads will move to 1.1 after we tell you. A 1.1 payload keeps every 1.0 key in the same place with the same meaning, and adds keys after them:
| Field | Meaning |
|---|---|
data.channel | Where the lead came in: web_chat, web_call, phone_call, sms, whatsapp, form, ad_form (an ad platform's own lead form, such as a Google lead form) or other. |
data.capture_method | How the lead was made: tool (the assistant saved it), analysis (read from the chat or call afterwards), form or manual. |
data.call_id | The call that captured the lead, when a call did. |
data.form_id, data.form_submission_id | The form and the submission that captured the lead, when a form did. |
A lead from a Google lead form has data.channel: "ad_form" and data.attribution.ad_form, the ids Google sent (lead_id, form_id, campaign_id, adgroup_id, creative_id, gcl_id and more) with capture_conversion: false, and no visit: the person never visited your site. Google already counted the lead as a conversion, so do not upload a lead conversion for it; upload only later outcomes, against gcl_id.
data.source keeps its meaning and values. conversation_id (top level and in data) is present only when the lead came from a conversation, and identity.assistant_id is null for a lead with no assistant behind it, such as a form. idempotency_key starts with the id of what captured the lead: the conversation, call or form submission. Branch on schema_version, and ignore keys you do not know.