Event reference

All outbound events share the envelope described in Outbound webhooks and add workspaceId and integrationId.

Event	Fires when	Subscription
`call.completed`	A call technically ended	Opt in
`call.outcome.updated`	A person or AI agent produced an outcome	Opt in
`call.missed`	An inbound call was not answered	Opt in
`call.failed`	A call failed technically	Opt in
`note.created`	A note was added to a contact	Opt in
`callback.created`	A callback was scheduled	Opt in
`meeting.created`	A meeting was scheduled	Opt in
`recording.ready`	A recording finished processing	Opt in
`dnc.created`	A number was added to Do Not Call	Opt in
`test.ping`	You click Test webhook	Test only

Select which events you receive in Integrations → Custom Integrations → Configure → Settings.

Shared fields

Ringee enriches outbound payloads with actor and correlation data before it queues them. These fields are optional so a lookup failure never drops the event.

Field	Shape or source
`data.user`	`{ id, email?, fullName? }`; the Ringee user the event belongs to. `email` is the primary address.
`data.agent`	`{ id, name }`; the AI Voice Agent behind the event. Absent for human-operated calls.
`data.externalId`	`metadata.external_id` or `metadata.externalId` from the originating AI Voice Agent call.
`data.contact`	`{ id, externalId?, phoneNumber, fullName?, email? }`
`data.company`	`{ id, externalId?, name }`
`data.call`	Telephony detail embedded by `call.outcome.updated`; it uses the same timing and number fields as a call event.

data.externalId is the caller-supplied correlation id for AI Voice Agent calls. It is independent from data.contact.externalId, which identifies a CRM contact linked through contact.upserted. Prefer the top-level data.externalId when present, then a linked contact id, then a normalized phone number.

data.user is omitted only when that user can no longer be resolved. data.agent and data.externalId are ownership-checked against the event’s workspace before Ringee adds them.

`call.completed`

A call has technically ended, regardless of whether anyone recorded an outcome yet. Required: data.callId, data.fromNumber, data.toNumber, data.status, data.direction, data.endedAt

string

required

Ringee call UUID. Use it as the unique key for the activity in your CRM.

string

required

Originating E.164 number.

string

required

Destination E.164 number.

string

required

Final call status reported by the carrier.

string

required

inbound or outbound; legacy call records may use incoming or outgoing.

string (ISO-8601)

required

When the call ended.

string (ISO-8601)

When the call was initiated.

string (ISO-8601)

When the call was answered.

number

Total billed duration.

string

pending, ready or unavailable.

object

Contact reference.

object

Company reference.

object

Ringee user the event belongs to, including the primary email when available.

object

AI Voice Agent reference with id and name when one placed the call. Absent for a human call.

string

Your correlation id from the AI Voice Agent call’s metadata.external_id or metadata.externalId.

{
  "event": "call.completed",
  "eventId": "evt_01HX5ZBN7Y0Q3S4M2K1WJ8V5DC",
  "occurredAt": "2026-05-23T14:42:18.000Z",
  "workspaceId": "org_2k7yX…",
  "integrationId": "ci_…",
  "data": {
    "callId": "f3b1…",
    "externalId": "crm-contact-42",
    "user": {
      "id": "usr_…",
      "email": "ada@babbage.example.com",
      "fullName": "Ada Lovelace"
    },
    "agent": { "id": "va_…", "name": "Sofia" },
    "fromNumber": "+14155550100",
    "toNumber": "+14155550123",
    "status": "completed",
    "direction": "outbound",
    "durationSeconds": 142,
    "startedAt": "2026-05-23T14:39:56.000Z",
    "endedAt": "2026-05-23T14:42:18.000Z"
  }
}

This event does not include the outcome. Outcomes arrive separately via call.outcome.updated, and may never arrive if the user never records one.

`call.outcome.updated`

A person recorded or changed an outcome, or an AI Voice Agent produced its post-call outcome. This can happen well after call.completed. Required: data.callId, data.outcome, data.updatedAt

string

required

Ringee call UUID — match it against an existing activity.

string

required

The CallOutcome value, for example sale, interested, meeting_booked, voicemail, no_answer.

string (ISO-8601)

required

When the outcome was set.

object

Telephony detail for the call: callId, fromNumber, toNumber, status, direction, startedAt, answeredAt, endedAt and durationSeconds. Omitted only when the call row can no longer be resolved.

string

Free-text note attached to the outcome.

object

Contact reference.

object

Company reference.

object

Ringee user the event belongs to.

object

AI Voice Agent reference with id and name when the outcome came from an agent call.

string

Your correlation id from the originating AI Voice Agent call.

string

AI Voice Agent call UUID.

string

AI Voice Agent UUID.

object

Caller-supplied metadata stored on the AI Voice Agent call.

{
  "event": "call.outcome.updated",
  "eventId": "evt_…",
  "occurredAt": "2026-05-23T14:50:00.000Z",
  "workspaceId": "org_…",
  "integrationId": "ci_…",
  "data": {
    "callId": "f3b1…",
    "call": {
      "callId": "f3b1…",
      "fromNumber": "+14155550100",
      "toNumber": "+14155550123",
      "status": "completed",
      "direction": "outbound",
      "startedAt": "2026-05-23T14:39:56.000Z",
      "answeredAt": "2026-05-23T14:40:02.000Z",
      "endedAt": "2026-05-23T14:42:18.000Z",
      "durationSeconds": 142
    },
    "externalId": "crm-contact-42",
    "user": {
      "id": "usr_…",
      "email": "ada@babbage.example.com",
      "fullName": "Ada Lovelace"
    },
    "agent": { "id": "va_…", "name": "Sofia" },
    "agentCallId": "8ddf384a-9b9d-44dd-a120-23395b1f4c98",
    "agentId": "7c819553-25be-43b5-9fc6-58effe1569f8",
    "outcome": "meeting_booked",
    "outcomeNote": "Demo scheduled for next Tuesday",
    "metadata": { "external_id": "crm-contact-42" },
    "updatedAt": "2026-05-23T14:50:00.000Z"
  }
}

Update or create the activity by callId — never create a second activity for the outcome. AI Voice Agent results and webhooks use Ringee’s canonical public names meeting_booked and callback_scheduled; historical stored names are normalized before they leave Ringee. When the outcome is meeting_booked, a separate meeting.created event also fires.

`call.missed`

An inbound call arrived but nobody picked up. Required: data.callId, data.fromNumber, data.toNumber, data.occurredAt

string

required

Ringee call UUID.

string

required

Originating number; normally the contact for a missed inbound call.

string

required

Workspace number that received the call.

string (ISO-8601)

required

When the missed call was recorded.

string

Carrier-provided reason.

object

Contact reference.

object

Company reference.

object

Ringee user the event belongs to.

object

AI Voice Agent reference with id and name when the event belongs to an agent call.

string

Your correlation id from the originating AI Voice Agent call.

{
  "event": "call.missed",
  "eventId": "evt_…",
  "occurredAt": "2026-05-23T15:20:00.000Z",
  "workspaceId": "org_…",
  "integrationId": "ci_…",
  "data": {
    "callId": "c_…",
    "user": {
      "id": "usr_…",
      "email": "ada@babbage.example.com",
      "fullName": "Ada Lovelace"
    },
    "fromNumber": "+14155550123",
    "toNumber": "+14155550100",
    "occurredAt": "2026-05-23T15:20:00.000Z"
  }
}

For missed calls, resolve the contact primarily from fromNumber.

`call.failed`

The telephony stack reported a hard failure — busy, invalid number, network error. Required: data.callId, data.fromNumber, data.toNumber, data.occurredAt

string

required

Ringee call UUID.

string

required

Originating number.

string

required

Destination number.

string (ISO-8601)

required

When the failure was recorded.

string

Carrier error code, for example USER_BUSY.

string

Human-readable description.

object

Contact reference.

object

Company reference.

object

Ringee user the event belongs to.

object

AI Voice Agent reference with id and name when one placed the failed call.

string

Your correlation id from the originating AI Voice Agent call.

{
  "event": "call.failed",
  "eventId": "evt_…",
  "occurredAt": "2026-05-23T15:25:00.000Z",
  "workspaceId": "org_…",
  "integrationId": "ci_…",
  "data": {
    "callId": "c_…",
    "externalId": "crm-contact-42",
    "user": {
      "id": "usr_…",
      "email": "ada@babbage.example.com",
      "fullName": "Ada Lovelace"
    },
    "agent": { "id": "va_…", "name": "Sofia" },
    "fromNumber": "+14155550100",
    "toNumber": "+14155550123",
    "occurredAt": "2026-05-23T15:25:00.000Z",
    "errorCode": "USER_BUSY"
  }
}

`note.created`

Required: data.noteId, data.contact, data.content, data.createdAt

string

required

Ringee note UUID.

object

required

Contact the note belongs to.

string

required

Note text.

string (ISO-8601)

required

When the note was created.

object

User who wrote the note.

object

Ringee user the event belongs to.

object

AI Voice Agent reference with id and name when one produced the event.

{
  "event": "note.created",
  "eventId": "evt_…",
  "occurredAt": "2026-05-23T15:00:00.000Z",
  "workspaceId": "org_…",
  "integrationId": "ci_…",
  "data": {
    "noteId": "n_…",
    "contact": {
      "id": "…",
      "externalId": "ext_contact_42",
      "phoneNumber": "+14155550123"
    },
    "user": {
      "id": "usr_…",
      "email": "ada@babbage.example.com",
      "fullName": "Ada Lovelace"
    },
    "content": "Prefers email follow-up.",
    "createdAt": "2026-05-23T15:00:00.000Z"
  }
}

`callback.created`

Required: data.callbackId, data.contact, data.scheduledAt, data.status, data.createdAt

string

required

Ringee callback UUID.

object

required

Contact to call back.

string (ISO-8601)

required

Scheduled callback time.

string

required

Current callback status.

string (ISO-8601)

required

When the callback was created.

string

Originating Ringee call UUID.

string

Free-text note.

object

Ringee user the event belongs to.

object

AI Voice Agent reference with id and name when the callback came from an agent call.

string

Your correlation id from the originating AI Voice Agent call.

{
  "event": "callback.created",
  "eventId": "evt_…",
  "occurredAt": "2026-05-23T15:05:00.000Z",
  "workspaceId": "org_…",
  "integrationId": "ci_…",
  "data": {
    "callbackId": "cb_…",
    "callId": "f3b1…",
    "externalId": "crm-contact-42",
    "contact": {
      "id": "…",
      "externalId": "ext_contact_42",
      "phoneNumber": "+14155550123"
    },
    "user": {
      "id": "usr_…",
      "email": "ada@babbage.example.com",
      "fullName": "Ada Lovelace"
    },
    "agent": { "id": "va_…", "name": "Sofia" },
    "scheduledAt": "2026-05-24T10:00:00.000Z",
    "status": "scheduled",
    "createdAt": "2026-05-23T15:05:00.000Z"
  }
}

`meeting.created`

Fires when a user schedules a meeting. Independent of outcomes — if the outcome is meeting_booked, both call.outcome.updated and meeting.created fire. Required: data.meetingId, data.contact, data.scheduledAt, data.status, data.createdAt

string

required

Ringee meeting UUID.

object

required

Contact invited to the meeting.

string (ISO-8601)

required

Scheduled meeting time.

string

required

Current meeting status.

string (ISO-8601)

required

When the meeting was created.

string

Meeting title.

number

Duration in minutes.

string

Physical location or video link.

string

Notes.

string

Calendar provider event id, when synced to Google or Microsoft.

string

Originating Ringee call UUID.

object

Ringee user the event belongs to.

object

AI Voice Agent reference with id and name when the meeting came from an agent call.

string

Your correlation id from the originating AI Voice Agent call.

{
  "event": "meeting.created",
  "eventId": "evt_…",
  "occurredAt": "2026-05-23T15:10:00.000Z",
  "workspaceId": "org_…",
  "integrationId": "ci_…",
  "data": {
    "meetingId": "m_…",
    "callId": "f3b1…",
    "externalId": "crm-contact-42",
    "contact": {
      "id": "…",
      "externalId": "ext_contact_42",
      "phoneNumber": "+14155550123"
    },
    "user": {
      "id": "usr_…",
      "email": "ada@babbage.example.com",
      "fullName": "Ada Lovelace"
    },
    "agent": { "id": "va_…", "name": "Sofia" },
    "scheduledAt": "2026-05-30T16:00:00.000Z",
    "status": "scheduled",
    "title": "Demo with Babbage Engines",
    "duration": 30,
    "createdAt": "2026-05-23T15:10:00.000Z"
  }
}

`recording.ready`

The recording has been processed and is downloadable. Required: data.recordingId, data.callId, data.url, data.createdAt

string

required

Ringee recording UUID.

string

required

Call UUID used to attach the recording to an activity.

string

required

Signed URL to the recording.

string (ISO-8601)

required

When the recording became available.

string

Audio container, for example mp3 or wav.

number

Duration in seconds.

string

Plain-text transcript, when available.

object

Ringee user the event belongs to.

object

AI Voice Agent reference with id and name when the recording belongs to an agent call.

string

Your correlation id from the originating AI Voice Agent call.

{
  "event": "recording.ready",
  "eventId": "evt_…",
  "occurredAt": "2026-05-23T14:43:00.000Z",
  "workspaceId": "org_…",
  "integrationId": "ci_…",
  "data": {
    "recordingId": "r_…",
    "callId": "f3b1…",
    "externalId": "crm-contact-42",
    "user": {
      "id": "usr_…",
      "email": "ada@babbage.example.com",
      "fullName": "Ada Lovelace"
    },
    "agent": { "id": "va_…", "name": "Sofia" },
    "url": "https://recordings.ringee.app/…",
    "format": "mp3",
    "durationSec": 142,
    "createdAt": "2026-05-23T14:43:00.000Z"
  }
}

Attach the recording to the activity matched by callId, and protect the URL behind your CRM’s existing access policies. Never expose recordings across organizations.

`dnc.created`

A phone number or contact was added to the Do Not Call list. Required: data.phoneNumber, data.createdAt

string

required

Number added to the Do Not Call list.

string (ISO-8601)

required

When the DNC entry was created.

string

Free-text reason.

string

Channel that triggered the addition.

object

Contact reference.

object

Ringee user the event belongs to.

object

AI Voice Agent reference with id and name when one produced the event.

{
  "event": "dnc.created",
  "eventId": "evt_…",
  "occurredAt": "2026-05-23T15:30:00.000Z",
  "workspaceId": "org_…",
  "integrationId": "ci_…",
  "data": {
    "phoneNumber": "+14155550123",
    "user": {
      "id": "usr_…",
      "email": "ada@babbage.example.com",
      "fullName": "Ada Lovelace"
    },
    "createdAt": "2026-05-23T15:30:00.000Z"
  }
}

On receipt, mark the contact as Do Not Call and disable your Call with Ringee button for it.

`test.ping`

Sent when you click Test webhook. Use it to validate signature verification end to end.

{
  "event": "test.ping",
  "eventId": "evt_test_1747999938000",
  "occurredAt": "2026-05-23T14:00:00.000Z",
  "workspaceId": "org_…",
  "integrationId": "ci_…",
  "data": { "message": "Hello from Ringee custom integrations." }
}

Return any 2xx response. Ringee ignores the response body; for example:

{ "received": true, "event": "test.ping" }

Machine-readable spec

The same definitions are available at runtime:

GET /api/integrations/custom/event-specs

It returns each event’s requiredFields, optionalFields, examplePayload and notes — useful for generating types or validating your handler in CI.

This is a management endpoint. It requires a signed-in Ringee admin session, not X-Ringee-Api-Key.

Get Started

CRM to Ringee

Ringee to CRM

Guides

Shared fields

`call.completed`

`call.outcome.updated`

`call.missed`

`call.failed`

`note.created`

`callback.created`

`meeting.created`

`recording.ready`

`dnc.created`

`test.ping`

Machine-readable spec

​Shared fields

​call.completed

​call.outcome.updated

​call.missed

​call.failed

​note.created

​callback.created

​meeting.created

​recording.ready

​dnc.created

​test.ping

​Machine-readable spec

Shared fields

`call.completed`

`call.outcome.updated`

`call.missed`

`call.failed`

`note.created`

`callback.created`

`meeting.created`

`recording.ready`

`dnc.created`

`test.ping`

Machine-readable spec