object
WebhookPayload
Signed webhook event body. Deduplicate deliveries by id, which matches the webhook-id header.
Variants
Use type to choose one of `contact.created`, `contact.updated`, `contact.archived`, `conversation.started`, `conversation.updated`, `conversation.closed`, `message.created`, `message.updated`, `webhook.test`.
ContactCreatedWebhookEvent
contact.createdRequired: `id`, `type`, `timestamp`, `data`.
- Name
id- Type
- string
- Description
- Event id. Matches the `webhook-id` header and is the consumer dedupe key.
- Name
type- Type
- enum
- Description
- Required property. Allowed values: contact.created.
- Name
timestamp- Type
- string
- Description
- Time when the source domain event happened.
- Name
data- Type
- ContactWebhookEventData
- Description
- Required property.
Example
contact.created
{
"id": "string",
"type": "contact.created",
"timestamp": "string",
"data": {
"contact": {
"id": "con_d7pibvs6gljrc2pfdc1g",
"tenantId": "tn_d7phk42ge9t9t6324f20",
"name": "Anna Kowalska",
"createdAt": "2026-04-30T09:20:00Z",
"updatedAt": "2026-04-30T10:10:00Z",
"conversations": [
{
"conversationId": "cnv_d7pigoip4tfcdebp5mlg",
"channel": "whatsapp",
"metadata": {
"phone_number": "+48123456789",
"wa_id": "48123456789"
}
}
],
"tagIds": [
"tag_d7pj8kaicb30377174j0"
],
"customFields": {
"cf_d7pgooc1v8t53cs68k5g": "customer",
"cf_d7pgpgin6fdi7ocdmdgg": "Krakow"
},
"archivedAt": null
}
}
}ContactUpdatedWebhookEvent
contact.updatedRequired: `id`, `type`, `timestamp`, `data`.
- Name
id- Type
- string
- Description
- Event id. Matches the `webhook-id` header and is the consumer dedupe key.
- Name
type- Type
- enum
- Description
- Required property. Allowed values: contact.updated.
- Name
timestamp- Type
- string
- Description
- Time when the source domain event happened.
- Name
data- Type
- ContactWebhookEventData
- Description
- Required property.
Example
contact.updated
{
"id": "string",
"type": "contact.updated",
"timestamp": "string",
"data": {
"contact": {
"id": "con_d7pibvs6gljrc2pfdc1g",
"tenantId": "tn_d7phk42ge9t9t6324f20",
"name": "Anna Kowalska",
"createdAt": "2026-04-30T09:20:00Z",
"updatedAt": "2026-04-30T10:10:00Z",
"conversations": [
{
"conversationId": "cnv_d7pigoip4tfcdebp5mlg",
"channel": "whatsapp",
"metadata": {
"phone_number": "+48123456789",
"wa_id": "48123456789"
}
}
],
"tagIds": [
"tag_d7pj8kaicb30377174j0"
],
"customFields": {
"cf_d7pgooc1v8t53cs68k5g": "customer",
"cf_d7pgpgin6fdi7ocdmdgg": "Krakow"
},
"archivedAt": null
}
}
}ContactArchivedWebhookEvent
contact.archivedRequired: `id`, `type`, `timestamp`, `data`.
- Name
id- Type
- string
- Description
- Event id. Matches the `webhook-id` header and is the consumer dedupe key.
- Name
type- Type
- enum
- Description
- Required property. Allowed values: contact.archived.
- Name
timestamp- Type
- string
- Description
- Time when the source domain event happened.
- Name
data- Type
- ContactWebhookEventData
- Description
- Required property.
Example
contact.archived
{
"id": "string",
"type": "contact.archived",
"timestamp": "string",
"data": {
"contact": {
"id": "con_d7pibvs6gljrc2pfdc1g",
"tenantId": "tn_d7phk42ge9t9t6324f20",
"name": "Anna Kowalska",
"createdAt": "2026-04-30T09:20:00Z",
"updatedAt": "2026-04-30T10:10:00Z",
"conversations": [
{
"conversationId": "cnv_d7pigoip4tfcdebp5mlg",
"channel": "whatsapp",
"metadata": {
"phone_number": "+48123456789",
"wa_id": "48123456789"
}
}
],
"tagIds": [
"tag_d7pj8kaicb30377174j0"
],
"customFields": {
"cf_d7pgooc1v8t53cs68k5g": "customer",
"cf_d7pgpgin6fdi7ocdmdgg": "Krakow"
},
"archivedAt": null
}
}
}ConversationStartedWebhookEvent
conversation.startedA session started in a conversation. Sent once per session, when its first customer message or human agent's message arrives. Outbound automated messages (API, journey, campaign or desk) sent while the conversation has no active session start no session; they are delivered without one. A conversation can have many sessions over its lifetime.
Required: `id`, `type`, `timestamp`, `data`.
- Name
id- Type
- string
- Description
- Event id. Matches the `webhook-id` header and is the consumer dedupe key.
- Name
type- Type
- enum
- Description
- Required property. Allowed values: conversation.started.
- Name
timestamp- Type
- string
- Description
- Time when the source domain event happened.
- Name
data- Type
- ConversationWebhookEventData
- Description
- Required property.
Example
conversation.started
{
"id": "string",
"type": "conversation.started",
"timestamp": "string",
"data": {
"session": {
"id": "string",
"status": "cold",
"started": true,
"owner": {}
},
"changedFields": [
"string"
],
"sessionId": "string",
"inboxId": "ibx_01HV8Y4QH7C8H1K5K0C8A2B9E4",
"conversation": {
"id": "cnv_d7pigoip4tfcdebp5mlg",
"channel": "whatsapp",
"externalId": "US.13491208655302741918",
"inboxId": "ibx_d7pi2efp0k7nba4e1mt0",
"name": "Anna Kowalska",
"contactId": "con_d7pibvs6gljrc2pfdc1g",
"contactName": "Anna Kowalska",
"status": "open",
"activeOwner": {
"type": "user",
"id": "usr_d7phtlmtf1g6fu9aj6jg"
},
"lastMessageAt": "2026-04-30T10:35:00Z",
"lastMessagePreview": "Thanks, I will check it now.",
"lastMessageSender": "customer"
},
"contact": {
"id": "con_d7pibvs6gljrc2pfdc1g",
"tenantId": "tn_d7phk42ge9t9t6324f20",
"name": "Anna Kowalska",
"createdAt": "2026-04-30T09:20:00Z",
"updatedAt": "2026-04-30T10:10:00Z",
"conversations": [
{
"conversationId": "cnv_d7pigoip4tfcdebp5mlg",
"channel": "whatsapp",
"metadata": {
"phone_number": "+48123456789",
"wa_id": "48123456789"
}
}
],
"tagIds": [
"tag_d7pj8kaicb30377174j0"
],
"customFields": {
"cf_d7pgooc1v8t53cs68k5g": "customer",
"cf_d7pgpgin6fdi7ocdmdgg": "Krakow"
},
"archivedAt": null
},
"inbox": {
"id": "ibx_d7pi2efp0k7nba4e1mt0",
"createdAt": "2026-04-30T09:00:00Z",
"updatedAt": "2026-04-30T09:10:00Z",
"tenantId": "tn_d7phk42ge9t9t6324f20",
"channel": "whatsapp",
"externalId": "112233445566778",
"createdBy": "usr_d7phosq4g7mv2l5b9l40",
"name": "Support WhatsApp",
"teamId": "tem_d7pi77577990sq67vgqg",
"status": {
"state": "active",
"reasons": []
},
"config": {
"phoneNumberId": "112233445566778"
}
}
}
}ConversationUpdatedWebhookEvent
conversation.updatedAn open session's status or owner changed; `changedFields` lists what changed, and changes that aren't visible in the payload (such as team access) send nothing. For example, a chatbot handing a session over to agents sends this event with `changedFields` `["status", "owner"]` and `session.status` `pending`. Starting and closing a session send `conversation.started` and `conversation.closed` instead, so `session.status` is never `closed` here.
Required: `id`, `type`, `timestamp`, `data`.
- Name
id- Type
- string
- Description
- Event id. Matches the `webhook-id` header and is the consumer dedupe key.
- Name
type- Type
- enum
- Description
- Required property. Allowed values: conversation.updated.
- Name
timestamp- Type
- string
- Description
- Time when the source domain event happened.
- Name
data- Type
- ConversationWebhookEventData
- Description
- Required property.
Example
conversation.updated
{
"id": "string",
"type": "conversation.updated",
"timestamp": "string",
"data": {
"session": {
"id": "string",
"status": "cold",
"started": true,
"owner": {}
},
"changedFields": [
"string"
],
"sessionId": "string",
"inboxId": "ibx_01HV8Y4QH7C8H1K5K0C8A2B9E4",
"conversation": {
"id": "cnv_d7pigoip4tfcdebp5mlg",
"channel": "whatsapp",
"externalId": "US.13491208655302741918",
"inboxId": "ibx_d7pi2efp0k7nba4e1mt0",
"name": "Anna Kowalska",
"contactId": "con_d7pibvs6gljrc2pfdc1g",
"contactName": "Anna Kowalska",
"status": "open",
"activeOwner": {
"type": "user",
"id": "usr_d7phtlmtf1g6fu9aj6jg"
},
"lastMessageAt": "2026-04-30T10:35:00Z",
"lastMessagePreview": "Thanks, I will check it now.",
"lastMessageSender": "customer"
},
"contact": {
"id": "con_d7pibvs6gljrc2pfdc1g",
"tenantId": "tn_d7phk42ge9t9t6324f20",
"name": "Anna Kowalska",
"createdAt": "2026-04-30T09:20:00Z",
"updatedAt": "2026-04-30T10:10:00Z",
"conversations": [
{
"conversationId": "cnv_d7pigoip4tfcdebp5mlg",
"channel": "whatsapp",
"metadata": {
"phone_number": "+48123456789",
"wa_id": "48123456789"
}
}
],
"tagIds": [
"tag_d7pj8kaicb30377174j0"
],
"customFields": {
"cf_d7pgooc1v8t53cs68k5g": "customer",
"cf_d7pgpgin6fdi7ocdmdgg": "Krakow"
},
"archivedAt": null
},
"inbox": {
"id": "ibx_d7pi2efp0k7nba4e1mt0",
"createdAt": "2026-04-30T09:00:00Z",
"updatedAt": "2026-04-30T09:10:00Z",
"tenantId": "tn_d7phk42ge9t9t6324f20",
"channel": "whatsapp",
"externalId": "112233445566778",
"createdBy": "usr_d7phosq4g7mv2l5b9l40",
"name": "Support WhatsApp",
"teamId": "tem_d7pi77577990sq67vgqg",
"status": {
"state": "active",
"reasons": []
},
"config": {
"phoneNumberId": "112233445566778"
}
}
}
}ConversationClosedWebhookEvent
conversation.closedA session closed. Sent once for every session that closes; `session.started` is `false` for a session no customer or human agent wrote in. A closed session is never reopened; the next message starts a new session in the same conversation.
Required: `id`, `type`, `timestamp`, `data`.
- Name
id- Type
- string
- Description
- Event id. Matches the `webhook-id` header and is the consumer dedupe key.
- Name
type- Type
- enum
- Description
- Required property. Allowed values: conversation.closed.
- Name
timestamp- Type
- string
- Description
- Time when the source domain event happened.
- Name
data- Type
- ConversationWebhookEventData
- Description
- Required property.
Example
conversation.closed
{
"id": "string",
"type": "conversation.closed",
"timestamp": "string",
"data": {
"session": {
"id": "string",
"status": "cold",
"started": true,
"owner": {}
},
"changedFields": [
"string"
],
"sessionId": "string",
"inboxId": "ibx_01HV8Y4QH7C8H1K5K0C8A2B9E4",
"conversation": {
"id": "cnv_d7pigoip4tfcdebp5mlg",
"channel": "whatsapp",
"externalId": "US.13491208655302741918",
"inboxId": "ibx_d7pi2efp0k7nba4e1mt0",
"name": "Anna Kowalska",
"contactId": "con_d7pibvs6gljrc2pfdc1g",
"contactName": "Anna Kowalska",
"status": "open",
"activeOwner": {
"type": "user",
"id": "usr_d7phtlmtf1g6fu9aj6jg"
},
"lastMessageAt": "2026-04-30T10:35:00Z",
"lastMessagePreview": "Thanks, I will check it now.",
"lastMessageSender": "customer"
},
"contact": {
"id": "con_d7pibvs6gljrc2pfdc1g",
"tenantId": "tn_d7phk42ge9t9t6324f20",
"name": "Anna Kowalska",
"createdAt": "2026-04-30T09:20:00Z",
"updatedAt": "2026-04-30T10:10:00Z",
"conversations": [
{
"conversationId": "cnv_d7pigoip4tfcdebp5mlg",
"channel": "whatsapp",
"metadata": {
"phone_number": "+48123456789",
"wa_id": "48123456789"
}
}
],
"tagIds": [
"tag_d7pj8kaicb30377174j0"
],
"customFields": {
"cf_d7pgooc1v8t53cs68k5g": "customer",
"cf_d7pgpgin6fdi7ocdmdgg": "Krakow"
},
"archivedAt": null
},
"inbox": {
"id": "ibx_d7pi2efp0k7nba4e1mt0",
"createdAt": "2026-04-30T09:00:00Z",
"updatedAt": "2026-04-30T09:10:00Z",
"tenantId": "tn_d7phk42ge9t9t6324f20",
"channel": "whatsapp",
"externalId": "112233445566778",
"createdBy": "usr_d7phosq4g7mv2l5b9l40",
"name": "Support WhatsApp",
"teamId": "tem_d7pi77577990sq67vgqg",
"status": {
"state": "active",
"reasons": []
},
"config": {
"phoneNumberId": "112233445566778"
}
}
}
}MessageCreatedWebhookEvent
message.createdRequired: `id`, `type`, `timestamp`, `data`.
- Name
id- Type
- string
- Description
- Event id. Matches the `webhook-id` header and is the consumer dedupe key.
- Name
type- Type
- enum
- Description
- Required property. Allowed values: message.created.
- Name
timestamp- Type
- string
- Description
- Time when the source domain event happened.
- Name
data- Type
- MessageWebhookEventData
- Description
- Required property.
Example
message.created
{
"id": "string",
"type": "message.created",
"timestamp": "string",
"data": {
"session": {},
"changedFields": [
"string"
],
"conversationId": "cnv_01HV8Z2JH0Q7K4M9N6P2A1B3C5",
"sessionId": "string",
"inboxId": "ibx_01HV8Y4QH7C8H1K5K0C8A2B9E4",
"message": {
"id": "msg_d7pj3rljs4umccbo6tdg",
"createdAt": "2026-04-30T10:36:00.412305Z",
"updatedAt": "2026-04-30T10:36:02Z",
"tenantId": "tn_d7phk42ge9t9t6324f20",
"conversationId": "cnv_d7pigoip4tfcdebp5mlg",
"senderType": "user",
"senderId": "usr_d7phosq4g7mv2l5b9l40",
"content": {
"type": "text",
"text": {
"body": "Hi Anna, your order is ready for pickup."
}
},
"deliveryStatus": "delivered",
"channelMessageId": "wamid.HBgLMjQxMjM0NTY3ODkVAgARGBI",
"clientMessageId": "reply-4827-1"
},
"conversation": {
"id": "cnv_d7pigoip4tfcdebp5mlg",
"channel": "whatsapp",
"externalId": "US.13491208655302741918",
"inboxId": "ibx_d7pi2efp0k7nba4e1mt0",
"name": "Anna Kowalska",
"contactId": "con_d7pibvs6gljrc2pfdc1g",
"contactName": "Anna Kowalska",
"status": "open",
"activeOwner": {
"type": "user",
"id": "usr_d7phtlmtf1g6fu9aj6jg"
},
"lastMessageAt": "2026-04-30T10:35:00Z",
"lastMessagePreview": "Thanks, I will check it now.",
"lastMessageSender": "customer"
},
"contact": {
"id": "con_d7pibvs6gljrc2pfdc1g",
"tenantId": "tn_d7phk42ge9t9t6324f20",
"name": "Anna Kowalska",
"createdAt": "2026-04-30T09:20:00Z",
"updatedAt": "2026-04-30T10:10:00Z",
"conversations": [
{
"conversationId": "cnv_d7pigoip4tfcdebp5mlg",
"channel": "whatsapp",
"metadata": {
"phone_number": "+48123456789",
"wa_id": "48123456789"
}
}
],
"tagIds": [
"tag_d7pj8kaicb30377174j0"
],
"customFields": {
"cf_d7pgooc1v8t53cs68k5g": "customer",
"cf_d7pgpgin6fdi7ocdmdgg": "Krakow"
},
"archivedAt": null
},
"inbox": {
"id": "ibx_d7pi2efp0k7nba4e1mt0",
"createdAt": "2026-04-30T09:00:00Z",
"updatedAt": "2026-04-30T09:10:00Z",
"tenantId": "tn_d7phk42ge9t9t6324f20",
"channel": "whatsapp",
"externalId": "112233445566778",
"createdBy": "usr_d7phosq4g7mv2l5b9l40",
"name": "Support WhatsApp",
"teamId": "tem_d7pi77577990sq67vgqg",
"status": {
"state": "active",
"reasons": []
},
"config": {
"phoneNumberId": "112233445566778"
}
}
}
}MessageUpdatedWebhookEvent
message.updatedRequired: `id`, `type`, `timestamp`, `data`.
- Name
id- Type
- string
- Description
- Event id. Matches the `webhook-id` header and is the consumer dedupe key.
- Name
type- Type
- enum
- Description
- Required property. Allowed values: message.updated.
- Name
timestamp- Type
- string
- Description
- Time when the source domain event happened.
- Name
data- Type
- MessageWebhookEventData
- Description
- Required property.
Example
message.updated
{
"id": "string",
"type": "message.updated",
"timestamp": "string",
"data": {
"session": {},
"changedFields": [
"string"
],
"conversationId": "cnv_01HV8Z2JH0Q7K4M9N6P2A1B3C5",
"sessionId": "string",
"inboxId": "ibx_01HV8Y4QH7C8H1K5K0C8A2B9E4",
"message": {
"id": "msg_d7pj3rljs4umccbo6tdg",
"createdAt": "2026-04-30T10:36:00.412305Z",
"updatedAt": "2026-04-30T10:36:02Z",
"tenantId": "tn_d7phk42ge9t9t6324f20",
"conversationId": "cnv_d7pigoip4tfcdebp5mlg",
"senderType": "user",
"senderId": "usr_d7phosq4g7mv2l5b9l40",
"content": {
"type": "text",
"text": {
"body": "Hi Anna, your order is ready for pickup."
}
},
"deliveryStatus": "delivered",
"channelMessageId": "wamid.HBgLMjQxMjM0NTY3ODkVAgARGBI",
"clientMessageId": "reply-4827-1"
},
"conversation": {
"id": "cnv_d7pigoip4tfcdebp5mlg",
"channel": "whatsapp",
"externalId": "US.13491208655302741918",
"inboxId": "ibx_d7pi2efp0k7nba4e1mt0",
"name": "Anna Kowalska",
"contactId": "con_d7pibvs6gljrc2pfdc1g",
"contactName": "Anna Kowalska",
"status": "open",
"activeOwner": {
"type": "user",
"id": "usr_d7phtlmtf1g6fu9aj6jg"
},
"lastMessageAt": "2026-04-30T10:35:00Z",
"lastMessagePreview": "Thanks, I will check it now.",
"lastMessageSender": "customer"
},
"contact": {
"id": "con_d7pibvs6gljrc2pfdc1g",
"tenantId": "tn_d7phk42ge9t9t6324f20",
"name": "Anna Kowalska",
"createdAt": "2026-04-30T09:20:00Z",
"updatedAt": "2026-04-30T10:10:00Z",
"conversations": [
{
"conversationId": "cnv_d7pigoip4tfcdebp5mlg",
"channel": "whatsapp",
"metadata": {
"phone_number": "+48123456789",
"wa_id": "48123456789"
}
}
],
"tagIds": [
"tag_d7pj8kaicb30377174j0"
],
"customFields": {
"cf_d7pgooc1v8t53cs68k5g": "customer",
"cf_d7pgpgin6fdi7ocdmdgg": "Krakow"
},
"archivedAt": null
},
"inbox": {
"id": "ibx_d7pi2efp0k7nba4e1mt0",
"createdAt": "2026-04-30T09:00:00Z",
"updatedAt": "2026-04-30T09:10:00Z",
"tenantId": "tn_d7phk42ge9t9t6324f20",
"channel": "whatsapp",
"externalId": "112233445566778",
"createdBy": "usr_d7phosq4g7mv2l5b9l40",
"name": "Support WhatsApp",
"teamId": "tem_d7pi77577990sq67vgqg",
"status": {
"state": "active",
"reasons": []
},
"config": {
"phoneNumberId": "112233445566778"
}
}
}
}WebhookTestEvent
webhook.testSent only by `POST /webhooks:verify` to confirm the endpoint. Respond with any 2xx. Carries no business data.
Required: `id`, `type`, `timestamp`, `data`.
- Name
id- Type
- string
- Description
- Event id. Matches the `webhook-id` header.
- Name
type- Type
- enum
- Description
- Required property. Allowed values: webhook.test.
- Name
timestamp- Type
- string
- Description
- Time when the test event was sent.
- Name
data- Type
- object
- Description
- Required property.
Example
webhook.test
{
"id": "string",
"type": "webhook.test",
"timestamp": "string",
"data": {}
}