Referência dos Webhooks

Nesta seção, você encontrará detalhes sobre os eventos que a Zatten pode enviar para a sua aplicação via webhook. Configure uma URL no seu painel para começar a receber esses eventos em tempo real.

Como funcionam os Webhooks?

Quando ocorrem ações específicas na plataforma, como a criação de um lead ou o recebimento de uma mensagem, enviamos uma requisição POST para a URL que você configurou. O corpo dessa requisição contém um payload JSON com todas as informações relevantes sobre o evento.

Eventos de Conversa e Lead

LEAD_CREATED

Enviado sempre que um novo lead é criado no sistema, seja por uma interação inicial ou manualmente.

{
  "type": "LEAD_CREATED",
  "lead": {
    "id": "lead_abc123def456",
    "name": "Cliente Potencial",
    "wa_id": "5511987654321",
    "thread_id": "thr_external_xyz789",
    "last_interaction": null,
    "conversation_expires_in": null,
    "created_at": "2025-10-09T20:00:00.000Z",
    "ai_response_block_until": null,
    "tags": [],
    "tenant_id": "tenant_acme_corp_789",
    "unread_messages": 1,
    "column_id": "col_new_lead_111",
    "notes": null,
    "metadata": null,
    "assigned_to_user": null,
    "assigned_to_team": null,
    "zatten_thread_id": "zt-thread-internal-123"
  },
  "attendant": {
    "id": "attendant_ia_pro_333",
    "meta_number_id": "102030405060708",
    "name": "Assistente Virtual"
  },
  "timestamp": "2025-10-09T20:00:00.000Z"
}

Campos do Payload:

type: string - Tipo do evento (LEAD_CREATED).
lead: object - Objeto contendo os dados do lead.
- id: string - Identificador único do lead.
- name: string | null - Nome do lead.
- wa_id: string - Número de WhatsApp do lead (E.164).
- thread_id: string | null - ID da thread externa (se aplicável).
- last_interaction: string | null - Data da última interação (ISO 8601).
- conversation_expires_in: string | null - Data de expiração da janela de conversa (ISO 8601).
- created_at: string - Data de criação do lead (ISO 8601).
- ai_response_block_until: string | null - Data até a qual a IA está bloqueada de responder.
- tags: string[] | null - Array com os IDs das tags do lead.
- tenant_id: string - ID da sua organização (tenant).
- unread_messages: number | null - Quantidade de mensagens não lidas.
- column_id: string | null - ID da coluna do Kanban onde o lead se encontra.
- notes: string | null - Anotações sobre o lead.
- metadata: object | null - Objeto com dados personalizados do lead.
- assigned_to_user: string | null - ID do usuário para o qual o lead está atribuído.
- assigned_to_team: string | null - ID da equipe para a qual o lead está atribuído.
- zatten_thread_id: string | null - ID da thread interna da Zatten.
attendant: object - Objeto com dados do atendente.
- id: string - Identificador único do atendente.
- meta_number_id: string | null - ID do número de telefone da Meta.
- name: string | null - Nome do atendente.
timestamp: string - Data e hora do evento (ISO 8601).

LEAD_INTERACTION

Enviado quando um lead envia uma nova mensagem.

{
  "type": "LEAD_INTERACTION",
  "lead": {
    "id": "lead_abc123def456",
    "name": "Cliente Potencial",
    "wa_id": "5511987654321",
    "thread_id": "thr_external_xyz789",
    "last_interaction": "2025-10-09T21:30:15.123Z",
    "conversation_expires_in": "2025-10-10T21:30:15.123Z",
    "created_at": "2025-10-09T20:00:00.000Z",
    "ai_response_block_until": null,
    "tags": ["tag_vip_123", "tag_followup_456"],
    "tenant_id": "tenant_acme_corp_789",
    "unread_messages": 2,
    "column_id": "col_negotiation_xyz",
    "notes": "Demonstrou interesse no plano Enterprise.",
    "metadata": {
      "origem": "webinar-outubro",
      "score_venda": 85
    },
    "assigned_to_user": "user_joao_silva_111",
    "assigned_to_team": "team_vendas_sp_222",
    "zatten_thread_id": "zt-thread-internal-123"
  },
  "attendant": {
    "id": "attendant_ia_pro_333",
    "meta_number_id": "102030405060708",
    "name": "Assistente Virtual"
  },
  "message": {
    "messages": ["Olá, bom dia!", "Gostaria de agendar uma demonstração."]
  },
  "timestamp": "2025-10-09T21:30:15.123Z"
}

Campos do Payload:

type: string - Tipo do evento (LEAD_INTERACTION).
lead: object - Objeto contendo os dados do lead.
- id: string - Identificador único do lead.
- name: string | null - Nome do lead.
- wa_id: string - Número de WhatsApp do lead (E.164).
- thread_id: string | null - ID da thread externa (se aplicável).
- last_interaction: string | null - Data da última interação (ISO 8601).
- conversation_expires_in: string | null - Data de expiração da janela de conversa (ISO 8601).
- created_at: string - Data de criação do lead (ISO 8601).
- ai_response_block_until: string | null - Data até a qual a IA está bloqueada de responder.
- tags: string[] | null - Array com os IDs das tags do lead.
- tenant_id: string - ID da sua organização (tenant).
- unread_messages: number | null - Quantidade de mensagens não lidas.
- column_id: string | null - ID da coluna do Kanban onde o lead se encontra.
- notes: string | null - Anotações sobre o lead.
- metadata: object | null - Objeto com dados personalizados do lead.
- assigned_to_user: string | null - ID do usuário para o qual o lead está atribuído.
- assigned_to_team: string | null - ID da equipe para a qual o lead está atribuído.
- zatten_thread_id: string | null - ID da thread interna da Zatten.
attendant: object - Objeto com dados do atendente.
- id: string - Identificador único do atendente.
- meta_number_id: string | null - ID do número de telefone da Meta.
- name: string | null - Nome do atendente.
message: object - Objeto com o conteúdo da mensagem.
- messages: string[] - Array com as mensagens enviadas pelo lead.
timestamp: string - Data e hora do evento (ISO 8601).

AI_RESPONSE

Enviado sempre que a inteligência artificial responde a um lead.

{
  "type": "AI_RESPONSE",
  "lead": {
    "id": "lead_abc123def456",
    "name": "Cliente Potencial",
    "wa_id": "5511987654321",
    "thread_id": "thr_external_xyz789",
    "last_interaction": "2025-10-09T21:30:20.456Z",
    "conversation_expires_in": "2025-10-10T21:30:15.123Z",
    "created_at": "2025-10-09T20:00:00.000Z",
    "ai_response_block_until": null,
    "tags": ["tag_vip_123", "tag_followup_456"],
    "tenant_id": "tenant_acme_corp_789",
    "unread_messages": 0,
    "column_id": "col_negotiation_xyz",
    "notes": "Demonstrou interesse no plano Enterprise.",
    "metadata": {
      "origem": "webinar-outubro",
      "score_venda": 85
    },
    "assigned_to_user": "user_joao_silva_111",
    "assigned_to_team": "team_vendas_sp_222",
    "zatten_thread_id": "zt-thread-internal-123"
  },
  "attendant": {
    "id": "attendant_ia_pro_333",
    "meta_number_id": "102030405060708",
    "name": "Assistente Virtual"
  },
  "message": {
    "messages": ["Olá! Claro, qual o melhor horário para você?"]
  },
  "timestamp": "2025-10-09T21:30:20.456Z"
}

Campos do Payload:

type: string - Tipo do evento (AI_RESPONSE).
lead: object - Objeto contendo os dados do lead.
- id: string - Identificador único do lead.
- name: string | null - Nome do lead.
- wa_id: string - Número de WhatsApp do lead (E.164).
- thread_id: string | null - ID da thread externa (se aplicável).
- last_interaction: string | null - Data da última interação (ISO 8601).
- conversation_expires_in: string | null - Data de expiração da janela de conversa (ISO 8601).
- created_at: string - Data de criação do lead (ISO 8601).
- ai_response_block_until: string | null - Data até a qual a IA está bloqueada de responder.
- tags: string[] | null - Array com os IDs das tags do lead.
- tenant_id: string - ID da sua organização (tenant).
- unread_messages: number | null - Quantidade de mensagens não lidas.
- column_id: string | null - ID da coluna do Kanban onde o lead se encontra.
- notes: string | null - Anotações sobre o lead.
- metadata: object | null - Objeto com dados personalizados do lead.
- assigned_to_user: string | null - ID do usuário para o qual o lead está atribuído.
- assigned_to_team: string | null - ID da equipe para a qual o lead está atribuído.
- zatten_thread_id: string | null - ID da thread interna da Zatten.
attendant: object - Objeto com dados do atendente.
- id: string - Identificador único do atendente.
- meta_number_id: string | null - ID do número de telefone da Meta.
- name: string | null - Nome do atendente.
message: object - Objeto com o conteúdo da mensagem.
- messages: string[] - Array com as mensagens enviadas pelo lead.
timestamp: string - Data e hora do evento (ISO 8601).

ERROR

Enviado quando ocorre um erro ao processar ou enviar uma mensagem.

{
  "type": "ERROR",
  "lead": {
    "id": "lead_abc123def456",
    "name": "Cliente Potencial",
    "wa_id": "5511987654321",
    "thread_id": "thr_external_xyz789",
    "last_interaction": "2025-10-09T21:30:20.456Z",
    "conversation_expires_in": "2025-10-10T21:30:15.123Z",
    "created_at": "2025-10-09T20:00:00.000Z",
    "ai_response_block_until": "2035-10-09T21:30:20.456Z",
    "tags": ["tag_vip_123", "tag_followup_456"],
    "tenant_id": "tenant_acme_corp_789",
    "unread_messages": 2,
    "column_id": "col_negotiation_xyz",
    "notes": "Demonstrou interesse no plano Enterprise.",
    "metadata": {
      "origem": "webinar-outubro",
      "score_venda": 85
    },
    "assigned_to_user": "user_joao_silva_111",
    "assigned_to_team": "team_vendas_sp_222",
    "zatten_thread_id": "zt-thread-internal-123"
  },
  "attendant": {
    "id": "attendant_ia_pro_333",
    "meta_number_id": "102030405060708",
    "name": "Assistente Virtual"
  },
  "message": {
    "error": "Failed to send message: Recipient is outside of the 24-hour conversation window.",
    "code": "ERROR_META_REENGAGEMENT - 131047"
  },
  "timestamp": "2025-10-11T22:15:00.000Z"
}

Campos do Payload:

type: string - Tipo do evento (ERROR).
lead: object - Objeto contendo os dados do lead.
- id: string - Identificador único do lead.
- name: string | null - Nome do lead.
- wa_id: string - Número de WhatsApp do lead (E.164).
- thread_id: string | null - ID da thread externa (se aplicável).
- last_interaction: string | null - Data da última interação (ISO 8601).
- conversation_expires_in: string | null - Data de expiração da janela de conversa (ISO 8601).
- created_at: string - Data de criação do lead (ISO 8601).
- ai_response_block_until: string | null - Data até a qual a IA está bloqueada de responder.
- tags: string[] | null - Array com os IDs das tags do lead.
- tenant_id: string - ID da sua organização (tenant).
- unread_messages: number | null - Quantidade de mensagens não lidas.
- column_id: string | null - ID da coluna do Kanban onde o lead se encontra.
- notes: string | null - Anotações sobre o lead.
- metadata: object | null - Objeto com dados personalizados do lead.
- assigned_to_user: string | null - ID do usuário para o qual o lead está atribuído.
- assigned_to_team: string | null - ID da equipe para a qual o lead está atribuído.
- zatten_thread_id: string | null - ID da thread interna da Zatten.
attendant: object - Objeto com dados do atendente.
- id: string - Identificador único do atendente.
- meta_number_id: string | null - ID do número de telefone da Meta.
- name: string | null - Nome do atendente.
message: object - Objeto com o conteúdo da mensagem.
- messages: string[] - Array com as mensagens enviadas pelo lead.
message: object - Objeto com a descrição do erro.
- error: string - Detalhes sobre o erro que ocorreu.
- code: string - Detalhes sobre o código do erro que ocorreu.
timestamp: string - Data e hora do evento (ISO 8601).

Eventos de Kanban e Tags

LEAD_KANBAN_UPDATED

Enviado quando o lead muda de coluna no Kanban.

{
  "event": "LEAD_KANBAN_UPDATED",
  "lead_id": "abc213def456",
  "lead_name": "Novo Cliente",
  "lead_phone": "5511999999999",
  "previous_column_id": "col111abc123",
  "previous_column_name": "Proposta Enviada",
  "previous_column_description": null,
  "new_column_id": "col333def456",
  "new_column_name": "Lead Quente",
  "new_column_description": null,
  "timestamp": "2025-08-18T14:30:58.939Z",
  "attendant_id": "def456abc123",
  "attendant_name": "Zatten",
  "current_tags": [],
  "lead_metadata": null
}

Campos do Payload:

event: string - Tipo do evento (LEAD_KANBAN_UPDATED).
lead_id: string - Identificador do lead.
lead_name: string - Nome do lead.
lead_phone: string - Número do lead em formato internacional (E.164).
previous_column_id: string - Identificador da coluna anterior.
previous_column_name: string - Nome da coluna anterior.
previous_column_description: string | null - Descrição da coluna anterior.
new_column_id: string - Identificador da nova coluna.
new_column_name: string - Nome da nova coluna.
new_column_description: string | null - Descrição da nova coluna.
timestamp: string - Data/hora da atualização (ISO 8601).
attendant_id: string - Identificador do atendente vinculado.
attendant_name: string - Nome do atendente.
current_tags: array - Lista de tags atuais atribuídas ao lead.
lead_metadata: array | null - Lista de propriedades adicionais do lead.

LEAD_TAG_ADDED

Enviado quando uma tag é adicionada a um lead.

{
  "event": "LEAD_TAG_ADDED",
  "lead_id": "abc213def456",
  "lead_name": "Novo Cliente",
  "lead_phone": "5511999999999",
  "tag_id": "tag999ghi123",
  "tag_name": "Só quer conversar",
  "tag_description": null,
  "current_tags": [
    {
      "id": "tag777def890",
      "name": "Esperando Retorno",
      "description": ""
    },
    {
      "id": "tag999ghi123",
      "name": "Só quer conversar",
      "description": ""
    }
  ],
  "timestamp": "2025-08-18T14:31:19.692Z",
  "attendant_id": "def456abc123",
  "attendant_name": "Zatten",
  "kanban_column_id": "col555ghi678",
  "kanban_column_name": "Lead Frio",
  "kanban_column_description": null,
  "lead_metadata": [
    {
      "prop_name": "nome_do_chefe",
      "prop_value": "teste"
    },
    {
      "prop_name": "cpf",
      "prop_value": "12345678909"
    }
  ]
}

Campos do Payload:

event: string - Tipo do evento (LEAD_TAG_ADDED).
lead_id: string - Identificador do lead.
lead_name: string - Nome do lead.
lead_phone: string - Número do lead (E.164).
tag_id: string - Identificador da tag adicionada.
tag_name: string - Nome da tag adicionada.
tag_description: string | null - Descrição da tag.
current_tags: array - Lista completa das tags atuais do lead.
timestamp: string - Data/hora da atualização (ISO 8601).
attendant_id: string - Identificador do atendente.
attendant_name: string - Nome do atendente.
kanban_column_id: string - Identificador da coluna atual do Kanban.
kanban_column_name: string - Nome da coluna atual.
kanban_column_description: string | null - Descrição da coluna atual.
lead_metadata: array - Lista de propriedades adicionais do lead.

LEAD_TAG_REMOVED

Enviado quando uma tag é removida de um lead.

{
  "event": "LEAD_TAG_REMOVED",
  "lead_id": "abc213def456",
  "lead_name": "Novo Cliente",
  "lead_phone": "5511999999999",
  "tag_id": "tag777def890",
  "tag_name": "Esperando Retorno",
  "tag_description": null,
  "current_tags": [],
  "timestamp": "2025-08-18T14:36:31.409Z",
  "attendant_id": "def456abc123",
  "attendant_name": "Zatten",
  "kanban_column_id": "col555ghi678",
  "kanban_column_name": "Lead Frio",
  "kanban_column_description": null,
  "lead_metadata": [
    {
      "prop_name": "nome_do_chefe",
      "prop_value": "Chefe"
    },
    {
      "prop_name": "cpf",
      "prop_value": "12345678909"
    }
  ]
}

Campos do Payload:

event: string - Tipo do evento (LEAD_TAG_REMOVED).
lead_id: string - Identificador do lead.
lead_name: string - Nome do lead.
lead_phone: string - Número do lead (E.164).
tag_id: string - Identificador da tag removida.
tag_name: string - Nome da tag removida.
tag_description: string | null - Descrição da tag.
current_tags: array - Lista de tags restantes (pode estar vazia).
timestamp: string - Data/hora da atualização (ISO 8601).
attendant_id: string - Identificador do atendente.
attendant_name: string - Nome do atendente.
kanban_column_id: string - Identificador da coluna atual do Kanban.
kanban_column_name: string - Nome da coluna atual.
kanban_column_description: string | null - Descrição da coluna atual.
lead_metadata: array - Lista de propriedades adicionais do lead.

Observações Importantes

Confirmação: Para confirmar o recebimento de um webhook, sua URL deve retornar uma resposta com status 2xx (ex: 200 ou 204). Qualquer outro status pode ser interpretado como uma falha.
Formato de Data: Todos os timestamps e campos de data/hora seguem o padrão ISO 8601 UTC.
Idempotência: Sua aplicação deve ser construída para lidar com a possibilidade de receber o mesmo evento mais de uma vez. Tornar o processamento do webhook idempotente (processar o mesmo evento múltiplas vezes sem criar resultados duplicados) é uma prática recomendada.
Dados Atualizados: O payload de cada evento sempre contém os dados mais atualizados daquele lead no momento em que a ação ocorreu.

Documentação dos Webhooks

​Como funcionam os Webhooks?

​Eventos de Conversa e Lead

​LEAD_CREATED

​LEAD_INTERACTION

​AI_RESPONSE

​ERROR

​Eventos de Kanban e Tags

​LEAD_KANBAN_UPDATED

​LEAD_TAG_ADDED

​LEAD_TAG_REMOVED

Como funcionam os Webhooks?

Eventos de Conversa e Lead

LEAD_CREATED

LEAD_INTERACTION

AI_RESPONSE

ERROR

Eventos de Kanban e Tags

LEAD_KANBAN_UPDATED

LEAD_TAG_ADDED

LEAD_TAG_REMOVED