BrightshoalDocsOpen console
MenuWebhook events

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.

Call event
{
  "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 }
}
Chat event
{
  "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" }
}
FieldMeaning
eventThe event type.
event_idUnique 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.
timestampWhen the event happened, ISO 8601 in UTC. Deliveries can arrive out of order; sort by this, not by arrival.
identityThe organization, project and assistant it belongs to. Call events add assistant_version.
metadataCall events only: the metadata you passed when you started the call, echoed back.
livemodefalse 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.
dataThe event's own fields.

Call events can also carry room_name and server_region; treat both as diagnostics.

Call events

EventFires when
call.startedThe assistant has joined the call and loaded its configuration.
call.connectedThe other person is on the line. For an outbound call, after they answer.
call.endedThe 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:

FieldMeaning
call_typeinbound, outbound or web.
ended_reasonWhy 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_numberThe two ends of the call, when known.
started_at, ended_at, duration_msTiming. duration_ms runs from connection to the end.
messagesThe 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.
usageBillable usage rows: type plus token counts (input_tokens, output_tokens) or audio_duration seconds.
recordings, recording_urlRecording references, when the call was recorded. Fetch playback links through GET/api/calls/{id}/recordings.
performanceLatency 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.

EventFires whendata
conversation.startedA 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.createdA 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.capturedThe 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_requestedThe assistant asked for a person to take over.reason, the last 20 transcript entries, visitor_id, lead_id.
conversation.callback_requestedThe visitor asked to be called back.phone, and when given slot_start (the time they prefer), note, visitor_id, lead_id.
conversation.takeover.startedA person took the conversation over.agent (id, and email and name when known), source (console or api).
conversation.takeover.releasedThe 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.analyzedA background analysis of the conversation finished.summary, structured, lead_id, through_seq, conversation_status, human_review, needs_review.
conversation.endedThe 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:

FieldMeaning
status, ended_reason, message_countHow and why it closed, and its length.
lead_idThe lead, if one was captured.
handoff_statusnone, 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_atHandoff timing.
human_outcome, human_metricsWhen a person took part: handled or abandoned, and their reply times.
transcriptThe whole conversation. Replies from a person read as assistant turns prefixed with [human agent] .
usageModel usage for the conversation.
analysisThe 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.

form.submitted
{
  "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"
  }
}
FieldMeaning
form_id, submission_idThe form and the submission, also at the top level. There is no conversation_id, and identity has no assistant.
data.form.kindenquiry, callback, support, newsletter, careers or other.
data.submission.fieldsThe fields as stored: trimmed, emails lowercased, a ticked consent as yes, a file field as its file names joined with ", ".
data.submission.utm, click_idsAttribution from the post, its page URL or the page context, or null.
data.submission.filesThe 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_idThe 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.channelwebsite, or google_lead_form for a Google lead form. After the other form keys.
data.submission.adFor 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):

lead.uncontacted
{
  "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:

lead.follow_up_due
{
  "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"
  }
}
FieldMeaning
data.waiting_secondsHow long the lead had waited when the event was sent, wall clock.
data.threshold_minutesThe project's wait.
data.counts_contact_hoursThe wait counted only the project's contact hours.
data.urlThe 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.

form.health.opened
{
  "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..."
  }
}
FieldMeaning
data.ruleform_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.severitywarning or critical.
data.reasonFor form_refusing, why posts are refused (such as refused_site, refused_fields, refused_paused); else null.
data.titleThe problem in words, as the console and Slack show it.
data.detailThe 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:

FieldMeaning
data.channelWhere 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_methodHow the lead was made: tool (the assistant saved it), analysis (read from the chat or call afterwards), form or manual.
data.call_idThe call that captured the lead, when a call did.
data.form_id, data.form_submission_idThe 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.

Stuck on webhook events?