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. 
{
  "event": "LEAD_CREATED",
  "lead_id": "abc213def456",
  "lead_name": "Novo Cliente",
  "lead_phone": "5511999999999",
  "thread_id": "zt-thread-123abc456def",
  "attendant_id": "def456abc123",
  "meta_number_id": "109876543210987",
  "created_at": "2025-09-10T22:45:10.123Z",
  "timestamp": "2025-09-10T22:45:10.123Z"
}
Campos do Payload:
  • event: string - Tipo do evento (LEAD_CREATED).
  • lead_id: string - Identificador do lead.
  • lead_name: string | null - Nome do lead, se houver.
  • lead_phone: string - Número de WhatsApp do lead (formato E.164).
  • thread_id: string - Identificador da thread interna da Zatten.
  • attendant_id: string - Identificador do atendente vinculado.
  • meta_number_id: string - Identificador do número de telefone (da Meta).
  • created_at: string - Data e hora em que o lead foi criado (ISO 8601).
  • timestamp: string - Data/hora da atualização (ISO 8601).

​
LEAD_INTERACTION

Enviado quando um lead envia uma nova mensagem dentro da janela de conversa de 24 horas. 
{
  "event": "LEAD_INTERACTION",
  "lead_id": "abc213def456",
  "lead_name": "Novo Cliente",
  "lead_phone": "5511999999999",
  "thread_id": "zt-thread-123abc456def",
  "attendant_id": "def456abc123",
  "meta_number_id": "109876543210987",
  "messages": [
    "Olá, gostaria de mais informações."
  ],
  "last_interaction": "2025-09-10T22:50:00.456Z",
  "conversation_expires_in": "2025-09-11T22:50:00.456Z",
  "created_at": "2025-08-18T14:30:00.000Z",
  "timestamp": "2025-08-18T14:30:00.000Z"
}
Campos do Payload:
  • event: string - Tipo do evento (LEAD_INTERACTION).
  • lead_id: string - Identificador do lead.
  • lead_name: string | null - O nome do lead.
  • lead_phone: string - Número de WhatsApp do lead.
  • thread_id: string - Identificador da thread interna da Zatten.
  • attendant_id: string - Identificador do atendente vinculado.
  • meta_number_id: string - Identificador do número de telefone (da Meta).
  • messages: array - Lista contendo as mensagens recebidas do lead.
  • last_interaction: string - Data e hora da última interação (ISO 8601).
  • conversation_expires_in: string - Data e hora em que a janela de conversa de 24 horas expira (ISO 8601).
  • created_at: string - Data de criação do lead (ISO 8601).
  • timestamp: string - Data/hora da atualização (ISO 8601).

​
AI_RESPONSE

Enviado sempre que a inteligência artificial responde a um lead. 
{
  "event": "AI_RESPONSE",
  "lead_id": "abc213def456",
  "lead_name": "Novo Cliente",
  "lead_phone": "5511999999999",
  "thread_id": "zt-thread-123abc456def",
  "attendant_id": "def456abc123",
  "meta_number_id": "109876543210987",
  "messages": [
    "Olá, Novo Cliente! Claro, em que posso ajudar?"
  ],
  "last_interaction": "2025-09-10T22:50:05.789Z",
  "conversation_expires_in": "2025-09-11T22:50:00.456Z",
  "created_at": "2025-08-18T14:30:00.000Z",
  "timestamp": "2025-08-18T14:30:00.000Z"
  
}
Campos do Payload:
  • event: string - Tipo do evento (AI_RESPONSE).
  • lead_id: string - Identificador do lead.
  • lead_name: string | null - Nome do lead.
  • lead_phone: string - Número de WhatsApp do lead.
  • thread_id: string - Identificador da thread interna da Zatten.
  • attendant_id: string - Identificador do atendente vinculado.
  • meta_number_id: string - Identificador do número de telefone (da Meta).
  • messages: array - Lista de strings contendo as respostas enviadas pela IA.
  • last_interaction: string - Data e hora da última interação (ISO 8601).
  • conversation_expires_in: string - Data em que a janela de conversa expira (ISO 8601).
  • created_at: string - Data de criação do lead (ISO 8601).
  • timestamp: string - Data/hora da atualização (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.