Integração de Webhooks

Webhooks permitem que você conecte o Attlas Chat ao seu backend, CRM ou ferramentas externas em tempo real. Sempre que um visitante interage com seu chat, por exemplo, fornecendo seus dados de contato ou agendando uma reunião, o Attlas envia uma requisição HTTP POST automatizada para o endpoint especificado.

Eventos principais

O Attlas dispara webhooks para quatro eventos principais:

Evento	Tipo	Disparado quando
`contact_created`	`contact`	Um novo lead ou contato é criado via conversa ou agendamento.
`contact_updated`	`contact`	O perfil ou os dados de um contato existente são atualizados em uma nova interação.
`event_created`	`calendar`	Um visitante agenda uma nova reunião no Google Calendar através do chat.
`event_canceled`	`calendar`	Uma reunião agendada é cancelada por você ou pelo visitante.

contact_created é enviado apenas quando um novo contato é criado. Se um visitante recorrente for reconhecido através de deduplicação (e-mail, telefone ou histórico de conversa), o Attlas emite contact_updated em seu lugar.

Como configurar Webhooks

Configurar um endpoint de webhook leva menos de um minuto:

Navegue até as Configurações do Chat.
Selecione a aba Integrações.
Localize o cartão Webhooks e clique em Conectar.
Insira a URL do Webhook de destino (deve ser um endpoint seguro https://).
(Opcional) Configure cabeçalhos HTTP personalizados se seu servidor de recebimento exigir tokens de cabeçalho específicos.
(Opcional) Gere um Segredo de Assinatura HMAC para verificar a autenticidade do payload.
Clique em Salvar para ativar.

Estrutura do payload

Cada payload é enviado como um objeto JSON contendo detalhes sobre o evento e o chat associado:

{
  "id": "5c6f8a0b-1234-4567-890a-bcdef1234567",
  "type": "contact",
  "event": "contact_created",
  "created_at": "2026-08-07T10:12:33.412Z",
  "chat_id": 42,
  "data": {
    "id": "b1e23456-7890-4abc-def0-1234567890ab",
    "firstname": "Ana",
    "email": "ana@example.com",
    "phone": "+33612345678",
    "source": "form",
    "kind": "lead_capture",
    "conversation_id": "9f0a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c",
    "history": [
      {
        "type": "user",
        "content": "Gostaria de agendar uma demonstração para amanhã",
        "manual": true,
        "timestampz": "2026-08-07T10:11:54.000Z"
      },
      {
        "type": "assistant",
        "content": "Claro! Qual horário funciona melhor para você?",
        "manual": false,
        "timestampz": "2026-08-07T10:12:01.000Z"
      }
    ]
  }
}

O objeto data inclui apenas campos não vazios. Campos opcionais que não foram fornecidos pelo visitante são omitidos para manter os payloads limpos.

Intenção do lead e canais (`kind`, `channel`, `whatsapp`)

Para eventos de contato, o Attlas enriquece o payload com metadados de intenção e canal:

kind: Identifica a intenção bruta da criação do contato:
- lead_capture: Envio de formulário padrão de captura de lead.
- human_request: Solicitação do visitante para falar com um humano.
- booking: Reunião agendada via Google Calendar.
- whatsapp: Interação via gatilho de WhatsApp.
channel: Especifica o canal de saída quando aplicável (por exemplo "whatsapp" quando o visitante é direcionado ao WhatsApp; omitido quando vazio).
whatsapp: O número do WhatsApp do visitante quando fornecido ou capturado.

Histórico da conversa e objetos de mensagem

Quando conversation_id estiver presente em data (para contact_created, contact_updated e event_created), o Attlas inclui o histórico completo de mensagens da conversa em data.history, do mais antigo para o mais recente. Cada mensagem em history contém:

type: "user" para mensagens do visitante, ou "assistant" para respostas da IA.
content: O conteúdo em texto da mensagem.
manual: true quando o visitante digitou a mensagem manualmente, ou false quando gerada ao clicar em um botão de resposta rápida ou enviada pelo assistente.
timestampz: Data e hora ISO 8601 de criação da mensagem.

Segurança e Verificação

Para garantir que as requisições sejam originadas do Attlas, você pode gerar um Segredo de Assinatura nas configurações do seu webhook. Quando ativado, cada requisição inclui um cabeçalho X-Attlas-Signature contendo um timestamp e uma assinatura HMAC-SHA256 (t=timestamp,v1=signature).

Entrega, tentativas e monitoramento

Verificações de segurança: URLs de destino devem usar https:// público. Endereços de localhost e IPs privados são bloqueados.
Timeouts e tentativas: As requisições têm um timeout de 10 segundos. Se seu servidor retornar um erro 5xx ou expirar, o Attlas automaticamente tenta reenviar até 3 vezes com backoff exponencial.
Logs de entrega: Você pode visualizar tentativas recentes de entrega, códigos de status e mensagens de erro diretamente no diálogo de configurações do Attlas.

Home

Aprender

MCP

Eventos principais

Como configurar Webhooks

Estrutura do payload

Intenção do lead e canais (`kind`, `channel`, `whatsapp`)

Histórico da conversa e objetos de mensagem

Segurança e Verificação

Entrega, tentativas e monitoramento

​Eventos principais

​Como configurar Webhooks

​Estrutura do payload

​Intenção do lead e canais (kind, channel, whatsapp)

​Histórico da conversa e objetos de mensagem

​Segurança e Verificação

​Entrega, tentativas e monitoramento

Eventos principais

Como configurar Webhooks

Estrutura do payload

Intenção do lead e canais (`kind`, `channel`, `whatsapp`)

Histórico da conversa e objetos de mensagem

Segurança e Verificação

Entrega, tentativas e monitoramento