
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_updatedem vez decontact_created. - Um agendamento de reunião envia tanto um evento de contato (
contact_createdoucontact_updated) quanto um eventoevent_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:- No painel do Attlas, selecione seu chat e navegue até Configurações > Integrações.
- Localize o card Webhooks e clique em Conectar (ou Configurar).
- Insira a URL do Webhook de destino (deve ser um endereço
https://seguro e acessível publicamente). - (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).
- (Opcional) Clique em Adicionar segredo de assinatura para gerar um segredo HMAC usado para verificar a autenticidade da requisição.
- Clique em Salvar para ativar seu endpoint.
- 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 objetodata 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 emanswers 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, comochoice,text,number,url,periodoucontact.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 etapaschoice).field: Nome da propriedade de contato (presente para etapascontact, comofirstname,lastname,email,phone,whatsappouschedule).
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
Quandoconversation_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:truese o visitante digitou a mensagem manualmente, oufalsese 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çalhoX-Attlas-Signature:
${t}.${rawBody}, combinando o timestamp t e a string exata do corpo bruto da requisição HTTP.
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 paralocalhost, 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
5xxou 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 cliente4xxsã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.

