Saltar para o conteúdo principal
Webhooks conectam seu chat Attlas ao seu backend, CRM ou ferramentas de automação externas em tempo real. Sempre que um visitante interage com seu chat, como enviar detalhes de contato, completar um formulário de várias etapas ou agendar uma reunião, o Attlas envia uma requisição HTTP POST automatizada para o seu endpoint especificado.
Integração de Webhook

Eventos principais

O Attlas dispara webhooks para cinco eventos principais em três categorias:
Roteamento de eventos e pares:
  • Se um visitante recorrente fornecer informações e for correspondido por email, telefone, número do WhatsApp ou ID da conversa, o Attlas emitirá contact_updated em vez de contact_created.
  • Um agendamento de reunião envia tanto um evento de contato (contact_created ou contact_updated) quanto um evento event_created.
  • Um formulário concluído com campos de contato envia tanto um evento de contato quanto um evento form_completed.
  • Como os eventos emparelhados são executados simultaneamente, os endpoints receptores devem rotear as cargas verificando o campo event.
Reuniões reagendadas: O Attlas não tem um evento event_rescheduled separado. Quando um compromisso é reagendado, o Attlas emite um evento event_canceled seguido de um novo evento event_created.

Como configurar Webhooks

Configurar um endpoint de webhook leva menos de um minuto:
  1. No painel do Attlas, selecione seu chat e navegue até Configurações > Integrações.
  2. Localize o card Webhooks e clique em Conectar (ou Configurar).
  3. Insira a URL do Webhook de destino (deve ser um endereço https:// seguro e acessível publicamente).
  4. (Opcional) Configure cabeçalhos HTTP personalizados se seu servidor receptor exigir tokens de autorização estáticos ou chaves de API (até 10 cabeçalhos).
  5. (Opcional) Clique em Adicionar segredo de assinatura para gerar um segredo HMAC usado para verificar a autenticidade da requisição.
  6. Clique em Salvar para ativar seu endpoint.
  7. Clique em Enviar teste para enviar uma carga de teste e confirmar que seu servidor responde com 200 OK.

Envelope da carga do webhook

Toda requisição de webhook contém um envelope JSON com metadados de entrega e um objeto data específico do evento:

Eventos de contato (contact_created, contact_updated)

Os eventos de contato são disparados sempre que um visitante deixa detalhes de contato por meio de um formulário de captura de leads, uma solicitação de atendimento humano, um gatilho do WhatsApp ou um agendamento no calendário.

Campos de contato

Intenção do lead (kind)

Use kind para identificar por que o contato foi criado:
  • new_lead: Visitante enviou detalhes por meio de um formulário de captura de leads ou prompt.
  • human_request: Visitante pediu para falar com um membro da equipe humana.
  • booking: Visitante agendou uma reunião pelo Google Calendar.
  • whatsapp: Visitante clicou em um gatilho do WhatsApp para continuar a conversa no WhatsApp.

Eventos de conclusão de formulário (form_completed)

Quando um visitante chega ao final de um formulário interativo em seu chat, o Attlas despacha um evento form_completed. Esse evento é disparado para todo formulário concluído, incluindo pesquisas, questionários e quizzes que não incluem campos de contato.

Campos de conclusão de formulário

Estrutura dos objetos de resposta

Cada entrada em answers representa uma pergunta respondida ou entrada de contato:
  • step_id: Identificador estável da etapa do formulário. Permanece inalterado mesmo se você editar o texto da pergunta posteriormente.
  • type: Tipo da etapa, como choice, text, number, url, period ou contact.
  • question: O rótulo da pergunta exibido para o visitante.
  • answer: Texto legível da resposta, formatado no idioma principal do proprietário do espaço de trabalho.
  • value: Resposta bruta, legível por máquina (string para texto, array de IDs para escolhas, ou um objeto { "start": "YYYY-MM-DD", "end": "YYYY-MM-DD" } para intervalos de data).
  • option_ids: Array de IDs das opções selecionadas (presente para etapas choice).
  • field: Nome da propriedade de contato (presente para etapas contact, como firstname, lastname, email, phone, whatsapp ou schedule).

Eventos de calendário (event_created, event_canceled)

Quando visitantes agendam ou cancelam compromissos por meio da integração com o Google Calendar, o Attlas entrega eventos de webhook de calendário.

event_created

Despachado imediatamente quando um compromisso é confirmado:

event_canceled

Despachado quando uma reunião é cancelada:
O histórico da conversa é omitido em eventos event_canceled para manter as cargas de cancelamento leves.

Objetos de histórico de conversa

Quando conversation_id está presente em contact_created, contact_updated, form_completed ou event_created, o Attlas inclui a sequência completa de mensagens em data.history, ordenadas cronologicamente da mais antiga para a mais recente. Cada item de mensagem contém:
  • type: "user" para entradas do visitante, ou "assistant" para respostas da IA.
  • content: Conteúdo da mensagem em texto.
  • manual: true se o visitante digitou a mensagem manualmente, ou false se foi enviada ao tocar em um botão de gatilho ou enviada pelo assistente.
  • timestampz: Data e hora ISO 8601 em que a mensagem foi registrada.

Segurança e verificação de assinatura

Para verificar se as requisições são originadas do Attlas e evitar adulteração, gere um Segredo de Assinatura nas suas configurações de webhook. Quando um segredo é configurado, o Attlas calcula uma assinatura HMAC-SHA256 e a anexa no cabeçalho X-Attlas-Signature:
A assinatura é calculada sobre ${t}.${rawBody}, combinando o timestamp t e a string exata do corpo bruto da requisição HTTP.
Sempre verifique assinaturas usando o corpo bruto da requisição, sem parse. Re-serializar um objeto JSON parseado altera formatação e espaços em branco, o que faz a verificação de assinatura falhar.

Exemplos de código de verificação

Cabeçalhos da requisição


Entrega, tentativas e monitoramento

  • Entrega assíncrona em segundo plano: O Attlas entrega webhooks em segundo plano usando after() do Next.js. Nem as interações dos visitantes, envios de formulários ou agendamentos no calendário são atrasados ou bloqueados pelo seu receptor de webhooks.
  • Proteção contra SSRF: As URLs de webhook devem usar endereços https:// públicos. Requisições para localhost, sufixos de domínio local (.local, .internal), faixas de IP de rede privada (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10) e serviços de metadados na nuvem (como 169.254.169.254) são rejeitadas. Redirecionamentos HTTP (3xx) são tratados como falhas para evitar travessia de rede baseada em redirecionamento.
  • Tempo limite e política de tentativas: As requisições têm um tempo limite estrito de 10 segundos. Se o seu endpoint retornar um erro de servidor 5xx ou encontrar um problema de rede, o Attlas tentará novamente a entrega automaticamente até 3 vezes com backoff exponencial (1s, 2s, 4s). Respostas com erros de cliente 4xx são tratadas como falhas permanentes e não serão tentadas novamente.
  • Registros de entrega: Você pode inspecionar as entregas recentes de webhooks diretamente no painel do Attlas abrindo Configurações > Integrações > Webhooks. Os registros exibem tipos de eventos, códigos de status HTTP, latência, erros, contagem de tentativas e cargas completas. Os registros de entrega são mantidos automaticamente por 30 dias.
Última modificação em 31 de outubro de 2026