Contact Webhook Events: Payloads for the contact.* Triggers

Contact events keep external systems in sync with your CloudTalk contact list. contact.created and contact.updated carry the full contact card; contact.deleted carries only the id. These are account-level webhooks, delivered to the endpoints you register under Account → Webhooks. See the overview. All examples show the full request body, including the envelope. Fields with empty values are omitted from payloads: they are never sent as null. Fields shown in bold are always present. A bold field nested inside an optional object is always present whenever that object is. Everything else is optional.

contact.created

Fires when a new contact is added to your account: created manually, imported, or added through an integration or the API. Use it to keep your CRM, helpdesk, or data warehouse in sync as new contacts appear.

Example

{
  "event_id": "018f4c2a-9b1d-8e3f-9a2b-6c5d4e3f2a10",
  "type": "contact.created",
  "version": "v1",
  "occurred_at": "2026-08-17T09:34:21.512Z",
  "company_id": "123456",
  "data": {
    "id": "44210",
    "type": "contact",
    "name": "Jane Doe",
    "company": "Acme Inc.",
    "title": "Head of Procurement",
    "industry": "Manufacturing",
    "website": "https://acme.example.com",
    "address": "1 Market Street",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94105",
    "phones": ["+12025550143", "+13105550166"],
    "emails": ["jane.doe@example.com", "j.doe@acme.example.com"],
    "country": { "name": "United States", "country_code": "US" },
    "tags": ["vip", "priority"],
    "custom_fields": { "crm_id": "CRM-00042", "segment": "enterprise" },
    "external_urls": [{ "name": "CRM profile", "url": "https://crm.example.com/contacts/42" }],
    "source": "api",
    "created_at": "2026-08-17T09:34:21.500Z",
    "modified_at": "2026-08-17T09:34:21.500Z",
    "favorite_user": {
      "id": "7",
      "name": "Ada Bennett",
      "first_name": "Ada",
      "last_name": "Bennett",
      "email": "ada.bennett@example.com",
      "role": "agent",
      "language": "en",
      "extension": "1007"
    }
  }
}

Field	Type	Description
`id`	string	The contact’s id in CloudTalk.
`type`	string	The contact kind: `contact` or `lead`.
`name`	string	The contact’s display name.
`company`	string	Company name on the contact card.
`title`	string	Job title.
`industry`	string	Industry label.
`website`	string	Website URL.
`address`	string	Street address. Related fields: `city`, `state`, `zip`.
`phones`	string[]	The contact’s phone numbers, in E.164 format.
`emails`	string[]	The contact’s email addresses.
`country`	object	The contact’s country: `{ "name": "United States", "country_code": "US" }`.
`tags`	string[]	Tag names on the contact.
`custom_fields`	object	Your custom fields as a key-value map of strings.
`external_urls`	object[]	Named external links on the contact. Each item: `{ "name": "...", "url": "..." }`.
`source`	string	Where the contact record originated.
`created_at`	string	When the contact was created.
`modified_at`	string	When the contact was last modified.
`favorite_user`	User	The user assigned to the contact as their favorite (preferred) agent, when one is set. Same shape as the user object on call events. Omitted when the contact has no favorite user or that user has since been deleted.

contact.updated

Fires whenever an existing contact’s details change: a renamed contact, an added phone number or email, edited tags and custom fields, or a change of favorite user. The payload carries the contact’s full, current profile (the same shape as contact.created), not just the fields that changed. You can simply overwrite your stored copy. To find out exactly what changed, compare the payload with the version you previously stored.

Example

{
  "event_id": "018f4c2a-9b1d-8f7a-9c3d-2e1f0a9b8c76",
  "type": "contact.updated",
  "version": "v1",
  "occurred_at": "2026-08-17T10:05:42.318Z",
  "company_id": "123456",
  "data": {
    "id": "44210",
    "type": "contact",
    "name": "Jane Doe",
    "company": "Acme Inc.",
    "title": "VP of Procurement",
    "phones": ["+12025550143"],
    "emails": ["jane.doe@example.com"],
    "country": { "name": "United States", "country_code": "US" },
    "tags": ["vip", "priority", "renewal-q3"],
    "custom_fields": { "crm_id": "CRM-00042", "segment": "enterprise" },
    "source": "api",
    "created_at": "2026-08-17T09:34:21.500Z",
    "modified_at": "2026-08-17T10:05:42.300Z",
    "favorite_user": {
      "id": "7",
      "name": "Ada Bennett",
      "first_name": "Ada",
      "last_name": "Bennett",
      "email": "ada.bennett@example.com",
      "role": "agent",
      "language": "en",
      "extension": "1007"
    }
  }
}

Because empty fields are omitted, a field cleared by an update simply disappears from the payload. Treat absence as empty when overwriting your copy.

contact.deleted

Fires when a contact is removed from your account. Because the record no longer exists, the payload contains only the deleted contact’s id. Use it to delete or archive the matching record in your connected systems.

Example

{
  "event_id": "018f4c2b-1c2d-8a4b-9e5f-7a6b5c4d3e21",
  "type": "contact.deleted",
  "version": "v1",
  "occurred_at": "2026-08-17T11:12:03.044Z",
  "company_id": "123456",
  "data": {
    "id": "44210"
  }
}

Field	Type	Description
`id`	string	The deleted contact’s id: matches the id from earlier `contact.created` and `contact.updated` events.

Treat a delete as terminal for that contact. Events are not guaranteed to arrive in order, so an earlier contact.updated can occasionally be delivered after the contact.deleted: order by occurred_at.

​contact.created

​contact.updated

​contact.deleted

contact.created

contact.updated

contact.deleted