Webhook events

Every webhook event Vocenya sends, the scope each one needs and an example payload for each.

Subscribe an endpoint to the events you need. Each event needs your key's webhooks:manage scope plus the read scope of its record. All events share the envelope {"id", "type", "livemode", "created_at", "data"} described in Webhooks; data differs per event.

Event	When it is sent	Scopes needed to subscribe
`lead.created`	A lead was captured	`leads:read`
`call.completed`	An inbound call ended	`calls:read`
`booking.created`	An appointment was booked	`bookings:read`
`chat.handed_off`	A website chat was handed to a person	`chats:read`
`outbound_call.completed`	An outbound call ended	`outbound:write`
`chat.started`	A visitor started a website chat	`chats:read`
`chat.message.created`	A website chat got a new message	`chats:read`
`chat.lead_captured`	A website chat captured a lead	`chats:read`, `leads:read`
`chat.handoff_requested`	The visitor or the AI asked for a person in a website chat	`chats:read`
`chat.closed`	A website chat was closed	`chats:read`

New event types may be added within the API version, so ignore types you do not handle.

Call events

call.completed carries the call's id, direction, status, numbers, times, duration_seconds and spam: true when the receptionist judged the call unwanted (no lead is created for it). Calls from numbers on your blocked callers list never reach anyone and send no event.

Live chat events

Every chat.* event carries the same chat object: id, status, page_url, handed_off_at, closed_at and created_at.

chat.message.created adds message. sender is who wrote it (visitor, ai, agent, owner or system), role is how the widget shows it (visitor, ai, team or system) and via_api is true for replies sent with the API. To build a bot, answer visitor messages with POST /chats/{chat}/messages and skip via_api: true, which are your own.
chat.lead_captured adds lead, with the same fields as lead.created.
chat.handoff_requested adds requested_by (visitor or ai) when a person is asked for. The chat is then with_agent (a GH Live agent has it) or with_owner (waiting for your team).
chat.handed_off also fires when your team takes a chat over by replying.
chat.closed adds chat.lead_id and chat.message_count.

HIPAA-mode accounts receive ids only, for example {"chat": {"id": 205}, "message": {"id": 4410}}.

Example payloads

These are the exact samples test deliveries send (a test delivery adds "sample": true to data).

lead.created

A lead was captured. Subscribing needs leads:read.

JSON

{
  "id": "9f0c6a1e-5b7d-4c1a-9e8f-2d3b4a5c6d7e",
  "type": "lead.created",
  "livemode": true,
  "created_at": "2026-10-02T14:03:30+00:00",
  "data": {
    "lead": {
      "id": 311,
      "call_id": 1042,
      "chat_conversation_id": null,
      "outbound_call_id": null,
      "name": "Jordan Smith",
      "phone_number": "+15555550123",
      "email": "[email protected]",
      "urgency": null,
      "custom_fields": [],
      "created_at": "2026-10-02T14:05:40+00:00"
    }
  }
}

call.completed

An inbound call ended. Subscribing needs calls:read.

JSON

{
  "id": "9f0c6a1e-5b7d-4c1a-9e8f-2d3b4a5c6d7e",
  "type": "call.completed",
  "livemode": true,
  "created_at": "2026-10-02T14:03:30+00:00",
  "data": {
    "call": {
      "id": 1042,
      "direction": "inbound",
      "status": "completed",
      "from_number": "+15555550123",
      "to_number": "+15555550199",
      "started_at": "2026-10-02T14:00:00+00:00",
      "ended_at": "2026-10-02T14:03:25+00:00",
      "duration_seconds": 205,
      "spam": false
    }
  }
}

booking.created

An appointment was booked. Subscribing needs bookings:read.

JSON

{
  "id": "9f0c6a1e-5b7d-4c1a-9e8f-2d3b4a5c6d7e",
  "type": "booking.created",
  "livemode": true,
  "created_at": "2026-10-02T14:03:30+00:00",
  "data": {
    "booking": {
      "id": 88,
      "call_id": 1042,
      "outbound_call_id": null,
      "provider": "google_calendar",
      "starts_at": "2026-10-05T15:30:00+00:00",
      "duration_minutes": 30,
      "name": "Jordan Smith",
      "phone_number": "+15555550123"
    }
  }
}

chat.handed_off

A website chat was handed to a person. Subscribing needs chats:read.

JSON

{
  "id": "9f0c6a1e-5b7d-4c1a-9e8f-2d3b4a5c6d7e",
  "type": "chat.handed_off",
  "livemode": true,
  "created_at": "2026-10-02T14:03:30+00:00",
  "data": {
    "chat": {
      "id": 205,
      "status": "with_owner",
      "page_url": "https://www.example.com/contact",
      "handed_off_at": "2026-10-02T14:06:00+00:00",
      "closed_at": null,
      "created_at": "2026-10-02T14:03:11+00:00"
    }
  }
}

outbound_call.completed

An outbound call ended. Subscribing needs outbound:write.

JSON

{
  "id": "9f0c6a1e-5b7d-4c1a-9e8f-2d3b4a5c6d7e",
  "type": "outbound_call.completed",
  "livemode": true,
  "created_at": "2026-10-02T14:03:30+00:00",
  "data": {
    "outbound_call": {
      "id": 57,
      "campaign_id": null,
      "source": "api",
      "purpose": "informational",
      "status": "completed",
      "contact_name": "Jordan Smith",
      "phone_number": "+15555550123",
      "blocked_reason": null,
      "answered_at": "2026-10-02T14:06:02+00:00",
      "answered_by": "human",
      "ended_at": "2026-10-02T14:08:40+00:00",
      "duration_seconds": 158
    }
  }
}

chat.started

A visitor started a website chat. Subscribing needs chats:read.

JSON

{
  "id": "9f0c6a1e-5b7d-4c1a-9e8f-2d3b4a5c6d7e",
  "type": "chat.started",
  "livemode": true,
  "created_at": "2026-10-02T14:03:30+00:00",
  "data": {
    "chat": {
      "id": 205,
      "status": "ai",
      "page_url": "https://www.example.com/contact",
      "handed_off_at": null,
      "closed_at": null,
      "created_at": "2026-10-02T14:03:11+00:00"
    }
  }
}

chat.message.created

A website chat got a new message. Subscribing needs chats:read.

JSON

{
  "id": "9f0c6a1e-5b7d-4c1a-9e8f-2d3b4a5c6d7e",
  "type": "chat.message.created",
  "livemode": true,
  "created_at": "2026-10-02T14:03:30+00:00",
  "data": {
    "chat": {
      "id": 205,
      "status": "ai",
      "page_url": "https://www.example.com/contact",
      "handed_off_at": null,
      "closed_at": null,
      "created_at": "2026-10-02T14:03:11+00:00"
    },
    "message": {
      "id": 4410,
      "sender": "visitor",
      "role": "visitor",
      "author": "Visitor",
      "body": "Hi, do you have any openings this week?",
      "via_api": false,
      "created_at": "2026-10-02T14:03:30+00:00"
    }
  }
}

chat.lead_captured

A website chat captured a lead. Subscribing needs chats:read and leads:read.

JSON

{
  "id": "9f0c6a1e-5b7d-4c1a-9e8f-2d3b4a5c6d7e",
  "type": "chat.lead_captured",
  "livemode": true,
  "created_at": "2026-10-02T14:03:30+00:00",
  "data": {
    "chat": {
      "id": 205,
      "status": "ai",
      "page_url": "https://www.example.com/contact",
      "handed_off_at": null,
      "closed_at": null,
      "created_at": "2026-10-02T14:03:11+00:00"
    },
    "lead": {
      "id": 311,
      "call_id": null,
      "chat_conversation_id": 205,
      "outbound_call_id": null,
      "name": "Jordan Smith",
      "phone_number": "+15555550123",
      "email": "[email protected]",
      "urgency": null,
      "custom_fields": [],
      "created_at": "2026-10-02T14:05:40+00:00"
    }
  }
}

chat.handoff_requested

The visitor or the AI asked for a person in a website chat. Subscribing needs chats:read.

JSON

{
  "id": "9f0c6a1e-5b7d-4c1a-9e8f-2d3b4a5c6d7e",
  "type": "chat.handoff_requested",
  "livemode": true,
  "created_at": "2026-10-02T14:03:30+00:00",
  "data": {
    "chat": {
      "id": 205,
      "status": "with_owner",
      "page_url": "https://www.example.com/contact",
      "handed_off_at": "2026-10-02T14:06:00+00:00",
      "closed_at": null,
      "created_at": "2026-10-02T14:03:11+00:00"
    },
    "requested_by": "visitor"
  }
}

chat.closed

A website chat was closed. Subscribing needs chats:read.

JSON

{
  "id": "9f0c6a1e-5b7d-4c1a-9e8f-2d3b4a5c6d7e",
  "type": "chat.closed",
  "livemode": true,
  "created_at": "2026-10-02T14:03:30+00:00",
  "data": {
    "chat": {
      "id": 205,
      "status": "closed",
      "page_url": "https://www.example.com/contact",
      "handed_off_at": "2026-10-02T14:06:00+00:00",
      "closed_at": "2026-10-02T14:20:12+00:00",
      "created_at": "2026-10-02T14:03:11+00:00",
      "lead_id": 311,
      "message_count": 14
    }
  }
}