O QuantumOutbound pode enviar dados de eventos para o seu servidor no momento em que algo acontece — um pedido de conexão é enviado, um prospeto aceita, uma mensagem é enviada ou recebida, ou uma conversa é etiquetada. Em vez de consultar a API constantemente, o seu endpoint recebe um pedido POST com todo o contexto.
Este guia mostra-lhe como configurar um endpoint de webhook, escolher os eventos que lhe interessam e processar o payload.
Pré-requisitos
- Uma conta QuantumOutbound com pelo menos um remetente ativo
- Um endpoint HTTPS acessível publicamente que possa receber pedidos POST
Como funcionam os webhooks
O QuantumOutbound dispara um webhook sempre que um evento relevante acontece num fio de conversa na sua caixa de entrada — seja desencadeado por uma ação de campanha ou por uma alteração manual que faça na interface. Cada evento envia um pedido HTTP POST para o URL que configurou.
Tipos de eventos disponíveis
| Tipo de evento | Dispara quando… |
|---|---|
activity.invitation.sent.v1 | Um pedido de conexão é enviado a um prospeto |
activity.connection.accepted.v1 | Um prospeto aceita o seu pedido de conexão |
activity.message.sent.v1 | Uma mensagem é enviada a um prospeto (incluindo mensagens automatizadas de campanha e follow-ups) |
activity.message.received.v1 | Um prospeto responde à sua conversa |
activity.threadbox.tags.update.v1 | Uma etiqueta é adicionada ou removida num fio de conversa |
Configurar o seu endpoint de webhook
- Na barra lateral esquerda, clique no ícone de Definições (engrenagem) na parte inferior.
- Clique em Webhooks.
- Cole o URL do seu endpoint HTTPS.
- Escolha os tipos de eventos que deseja receber.
- Selecione de quais agentes pretende receber eventos.
- Clique em Guardar.
💡 Dica: Use o botão Test para enviar um payload de exemplo para o seu endpoint. Isto confirma que o seu servidor consegue receber pedidos antes de quaisquer eventos reais serem disparados.
Compreender o payload
Cada entrega de webhook envia um objeto JSON com três campos de nível superior e um objeto data aninhado contendo todo o contexto.
Campos de nível superior:
| Campo | Descrição | Exemplo |
|---|---|---|
id | ID único de entrega (usado como chave de idempotência) | df313559-7cb1-... |
type | O tipo de evento | activity.connection.accepted.v1 |
timestamp | Quando o evento ocorreu (ISO 8601) | 2026-02-06T05:05:36+01:00 |
O objeto data contém estas secções:
| Secção | O que contém |
|---|---|
data.agent | Nome do seu agente, detalhes da empresa, serviços, tom de marca e playbook de vendas |
data.campaign | ID da campanha, nome, estado, objetivo, URL da página do produto, URL da landing page e tipo de campanha |
data.campaignContact | Estado do contacto na campanha (ex. invitation_send), detalhes da última atividade e indicador de terminação |
data.threadBox | Nomes completos do remetente e contacto, array de etiquetas, estado da conversa, pontuação de compatibilidade, raciocínio IA, nome do persona e estado de resposta |
data.sender | Perfil LinkedIn completo da conta remetente, info de contacto da base de conhecimento e análise de personalidade MBTI |
data.contact | Perfil LinkedIn do prospeto, título, resumo, localização, competências, empresas atuais e análise MBTI |
data.messages | Array de mensagens no fio de conversa |
Cabeçalhos de segurança incluídos em cada entrega:
| Cabeçalho | Descrição |
|---|---|
webhook-signature | Assinatura HMAC para verificar que o pedido veio do QuantumOutbound |
webhook-timestamp | Marca temporal Unix de quando o payload foi enviado |
webhook-idempotency-key | Chave única para evitar o processamento de entregas duplicadas |
webhook-key-id | Identifica qual chave de assinatura foi utilizada |
💡 Dica: O payload completo é grande e inclui todo o contexto do agente. Envie primeiro um webhook de teste para o seu endpoint e depois use esse JSON para mapear apenas os campos que precisa no seu handler.
Consultar o histórico de entregas
Pode verificar se um webhook foi disparado e rever o seu estado de entrega diretamente na aplicação. Vá a Definições → Webhooks para ver as entregas recentes, os seus códigos de estado e marcas temporais.
Erros comuns
"O teste funciona mas os eventos reais não disparam"
Certifique-se de que tem uma campanha ativa com prospetos a avançar no fluxo de trabalho. Os webhooks disparam quando o sistema executa uma ação (envia um convite, envia uma mensagem, recebe uma resposta, etiqueta um fio) ou quando altera manualmente uma etiqueta. Se não houver atividade, não há eventos para enviar.
"Recebo eventos mas faltam campos no payload"
O payload varia ligeiramente consoante o tipo de evento. Um evento activity.invitation.sent.v1 não terá campos relacionados com respostas, por exemplo. Verifique o payload de teste para o seu tipo de evento específico para ver quais campos estão incluídos.
"O payload é muito grande"
Isto é esperado. Cada entrega inclui o contexto completo do agente (serviços, playbook de vendas, tom de marca) para que o seu handler tenha tudo o que precisa para encaminhar e processar o evento. Faça parse apenas dos campos que necessita.
Pontos-chave
- Os webhooks enviam dados em tempo real para o seu servidor quando eventos acontecem — tanto ações automatizadas de campanha como alterações manuais.
- Cinco tipos de eventos cobrem todo o ciclo de prospeção: convite enviado, conexão aceite, mensagem enviada, mensagem recebida e etiqueta atualizada.
- O payload inclui o contexto completo do agente, campanha e contacto numa estrutura JSON aninhada.
- Os cabeçalhos de segurança permitem-lhe verificar que cada entrega veio do QuantumOutbound.
- Comece com um webhook de teste para capturar a estrutura completa do payload antes de desenvolver o seu handler.