object

WebhookPayload

LLM

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.created

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: 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.updated

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: 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.archived

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: 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.started

A session started in a conversation. Sent once per session, when its first customer message or human agent's message arrives: either the message creates the session, or it arrives in a session that so far has only outbound automated messages. A session created `cold` by an outbound automated message (API, journey, campaign or chatbot) doesn't send this event when it's created. 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.updated

An 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.closed

A session closed. Sent once for every session that closes, including a `cold` session with only outbound automated messages that nobody replied to; `session.started` is `false` for those. 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.created

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: 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": {
      "id": "string"
    },
    "changedFields": [
      "string"
    ],
    "conversationId": "cnv_01HV8Z2JH0Q7K4M9N6P2A1B3C5",
    "sessionId": "string",
    "inboxId": "ibx_01HV8Y4QH7C8H1K5K0C8A2B9E4",
    "message": {
      "id": "msg_d7pj3rljs4umccbo6tdg",
      "createdAt": "2026-04-30T10:36:00Z",
      "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.updated

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: 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": {
      "id": "string"
    },
    "changedFields": [
      "string"
    ],
    "conversationId": "cnv_01HV8Z2JH0Q7K4M9N6P2A1B3C5",
    "sessionId": "string",
    "inboxId": "ibx_01HV8Y4QH7C8H1K5K0C8A2B9E4",
    "message": {
      "id": "msg_d7pj3rljs4umccbo6tdg",
      "createdAt": "2026-04-30T10:36:00Z",
      "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.test

Sent 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": {}
}

Related operations

Webhook payloadsPOST {configured webhook URL}

Variants

ContactCreatedWebhookEvent

contact.created

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: 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.updated

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: 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.archived

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: 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.started

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.updated

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.closed

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.created

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: 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": {
      "id": "string"
    },
    "changedFields": [
      "string"
    ],
    "conversationId": "cnv_01HV8Z2JH0Q7K4M9N6P2A1B3C5",
    "sessionId": "string",
    "inboxId": "ibx_01HV8Y4QH7C8H1K5K0C8A2B9E4",
    "message": {
      "id": "msg_d7pj3rljs4umccbo6tdg",
      "createdAt": "2026-04-30T10:36:00Z",
      "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.updated

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: 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": {
      "id": "string"
    },
    "changedFields": [
      "string"
    ],
    "conversationId": "cnv_01HV8Z2JH0Q7K4M9N6P2A1B3C5",
    "sessionId": "string",
    "inboxId": "ibx_01HV8Y4QH7C8H1K5K0C8A2B9E4",
    "message": {
      "id": "msg_d7pj3rljs4umccbo6tdg",
      "createdAt": "2026-04-30T10:36:00Z",
      "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.test

Sent 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": {}
}