Usar Webhooks

O SalesMind AI pode enviar dados de eventos ao seu servidor no momento em que algo acontece — sai um pedido de conexão, um prospecto aceita, uma mensagem é enviada ou recebida, ou uma conversa recebe uma etiqueta. Em vez de consultar a API, o seu endpoint recebe uma requisição POST com todo o contexto.

Este guia mostra como configurar um endpoint de webhook, escolher os eventos que importam para você e lidar com a carga útil.

Pré-requisitos

• Uma conta do SalesMind AI com pelo menos um sender ativo
• Um endpoint HTTPS acessível publicamente que possa receber requisições POST

Como os webhooks funcionam

O SalesMind AI dispara um webhook sempre que um evento relevante acontece em um thread de conversa na sua caixa de entrada — seja por uma ação de campanha ou por uma alteração manual que você faz na interface. Cada evento envia uma requisição HTTP POST para a URL que você configurou.

Tipos de evento disponíveis

Tipo de evento	Dispara quando…
activity.invitation.sent.v1	Um pedido de conexão é enviado a um prospecto
activity.connection.accepted.v1	Um prospecto aceita o seu pedido de conexão
activity.message.sent.v1	Uma mensagem é enviada a um prospecto (incluindo mensagens automáticas de campanha e follow-ups)
activity.message.received.v1	Um prospecto responde à sua conversa
activity.threadbox.tags.update.v1	Uma etiqueta é adicionada ou removida em um thread de conversa

Estes cinco eventos activity.* são os que uma conta normal pode assinar e receber. Existe um sexto evento, user.register.v1, mas ele é somente para administradores — contas normais nunca o recebem, e ele é removido automaticamente se você tentar assiná-lo. webhook.test.v1 é um evento único enviado pelo botão Test, não algo que você assina.

Configurar o seu endpoint de webhook

1. Na barra lateral esquerda, clique no ícone de engrenagem Configurações na parte de baixo.
2. Clique em Webhooks.
3. Cole a URL do seu endpoint HTTPS.
4. Escolha os tipos de evento que você quer receber.
5. Selecione de quais agentes você quer receber eventos.
6. Clique em Salvar.

💡 Dica: Use o botão Test para enviar uma carga útil de exemplo ao seu endpoint. Isso confirma que o seu servidor consegue receber requisições antes de qualquer evento real disparar.

Gerenciar endpoints com a API

Você pode gerenciar os endpoints de webhook pela API em vez da interface. Cada endpoint precisa do seu cabeçalho X-API-KEY e fica sob https://api.sales-mind.ai//v1/webhooks.

Método	Endpoint	Finalidade
POST	/v1/webhooks/endpoints	Registrar um novo endpoint
GET	/v1/webhooks/endpoints	Listar seus endpoints
GET	/v1/webhooks/endpoints/{id}	Obter um endpoint
DELETE	/v1/webhooks/endpoints/{id}	Excluir um endpoint
GET	/v1/webhooks/endpoints/{id}/rotate-secret	Obter um novo segredo de assinatura
PUT	/v1/webhooks/endpoints/{id}/suspend	Suspender ou retomar um endpoint
GET	/v1/webhooks/events	Listar os eventos que você pode assinar
PUT	/v1/webhooks/endpoints/{id}/events	Alterar os eventos assinados
GET	/v1/webhooks/endpoints/{id}/test	Enviar uma entrega de teste

⚠️ O registro não retorna o seu segredo de assinatura. Depois de registrar um endpoint, chame rotate-secret para obter o segredo com o qual você verifica as entregas.

Seu endpoint deve ser uma URL HTTPS pública. O SalesMind AI verifica isso ao entregar um evento, não ao registrar — então uma URL não HTTPS ou privada é aceita no começo e depois falha na entrega.

Entender a carga útil

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 da 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 seções:

Seção	O que contém
data.agent	O nome do seu agente, detalhes da empresa, serviços, tom da marca e playbook de vendas
data.campaign	ID da campanha, nome, status, objetivo, URL da página de produto, URL da landing page e tipo de campanha
data.campaignContact	Status do contato na campanha (ex.: invitation_send), detalhes da última atividade e flag de encerrado
data.threadBox	Nomes completos do sender e do contato, array de etiquetas, status da conversa, fit score, justificativa da IA, nome da persona e status de resposta
data.sender	Perfil completo do LinkedIn da conta que envia, dados de contato da base de conhecimento e análise de personalidade MBTI
data.contact	Perfil do LinkedIn do prospecto, título, resumo, localização, competências, empresas atuais e análise MBTI
data.messages	Array de mensagens do thread da conversa

💡 Dica: A carga útil completa é grande e inclui todo o contexto do agente. Envie primeiro um webhook de teste ao seu endpoint e depois use esse JSON para mapear apenas os campos de que você precisa no seu handler.

Verificar a assinatura

Cada entrega carrega quatro cabeçalhos para você confirmar que ela realmente veio do SalesMind AI:

Cabeçalho	Valor
Webhook-Signature	HMAC-SHA256 codificado em Base64 da string assinada
Webhook-Timestamp	Segundos de época Unix, usados dentro da string assinada
Webhook-Idempotency-Key	{eventId}:{endpointId} — use para descartar entregas duplicadas
Webhook-Key-Id	current — qual segredo de assinatura foi usado

A string assinada é:

{Webhook-Timestamp}.{endpointId}.{sha256_hex(rawBody)}

Assine o valor do cabeçalho Webhook-Timestamp, não o campo timestamp ISO dentro do corpo — eles são diferentes.

Para verificar uma entrega:

1. Leia o corpo bruto da requisição, o cabeçalho Webhook-Timestamp e o cabeçalho Webhook-Signature.
2. Calcule o resumo SHA-256 em hex do corpo bruto e depois monte {Webhook-Timestamp}.{endpointId}.{sha256_hex}.
3. Calcule Base64(HMAC-SHA256(essa string, o segredo do seu endpoint)) e compare com Webhook-Signature usando uma comparação de tempo constante.
4. Opcionalmente, rejeite a entrega se Webhook-Timestamp for mais antigo que uma janela que você escolher (por exemplo, 5 minutos).

💡 A janela de reenvio de 5 minutos é uma verificação que você adiciona do seu lado. O SalesMind AI não a impõe.

⚠️ Depois de rotacionar o seu segredo, atualize o segredo guardado imediatamente. O SalesMind AI sempre assina com o segredo atual, então as entregas passam para o novo segredo na hora — não há período de tolerância no lado da assinatura.

Verificar o histórico de entregas

Você pode verificar se um webhook disparou e revisar o status da entrega diretamente no app. Vá em Configurações → Webhooks para ver as entregas recentes, seus códigos de status e horários.

Você também pode obter as entregas pela API:

Método	Endpoint	Finalidade
GET	/v1/webhooks/deliveries	Listar entregas (filtre por endpointId, status, type)
GET	/v1/webhooks/deliveries/{id}	Obter uma entrega, com sua carga útil
POST	/v1/webhooks/deliveries/{id}/replay	Reenviar uma entrega como um novo evento

Cada entrega tem um status: pending, delivered, failed ou suspended.

Como funcionam as tentativas de entrega:

• Cada tentativa expira após 5 segundos.
• Uma resposta 2xx marca a entrega como delivered e reinicia o contador de falhas do endpoint.
• Qualquer outra resposta — ou um tempo esgotado — a marca como failed e tenta de novo com um backoff de 5, 10, 20, 60 e depois 300 segundos (até 5 novas tentativas, ou seja, 6 tentativas no total).
• Após 10 falhas consecutivas, o SalesMind AI suspende o endpoint automaticamente. Novos eventos para um endpoint suspenso são registrados como suspended e ignorados até você retomá-lo.

Erros comuns

"O teste funciona mas os eventos reais não disparam"

Certifique-se de ter uma campanha ativa com prospectos avançando pelo fluxo. Os webhooks disparam quando o sistema executa uma ação (envia um convite, envia uma mensagem, recebe uma resposta, etiqueta um thread) ou quando você muda uma etiqueta manualmente. Se não há atividade, não há eventos para enviar.

"Estou recebendo eventos mas faltam campos na carga útil"

A carga útil varia um pouco conforme o tipo de evento. Um evento activity.invitation.sent.v1 não terá campos relacionados a respostas, por exemplo. Verifique a carga útil de teste do seu tipo de evento específico para ver quais campos estão incluídos.

"A carga útil é muito grande"

Isso é esperado. Cada entrega inclui todo o contexto do agente (serviços, playbook de vendas, tom da marca) para que o seu handler tenha tudo o que precisa para rotear e processar o evento. Analise apenas os campos de que você precisa.

"Minha URL de endpoint foi aceita mas nunca recebe nada"

Seu endpoint deve ser uma URL HTTPS pública. O SalesMind AI verifica isso ao entregar um evento, não ao registrar — então uma URL não HTTPS ou privada é aceita no começo e depois falha na entrega. Verifique o seu histórico de entregas em busca de tentativas com falha.

Principais conclusões

• Os webhooks enviam dados em tempo real ao seu servidor quando eventos acontecem — tanto ações automáticas de campanha quanto alterações manuais.
• Uma conta normal assina os cinco eventos activity.*; user.register.v1 é somente para administradores e webhook.test.v1 é apenas o evento de teste.
• Gerencie endpoints, eventos e entregas pela API sob https://api.sales-mind.ai//v1/webhooks — autentique-se com X-API-KEY.
• Verifique cada entrega com os cabeçalhos Webhook-Signature e Webhook-Timestamp; o segredo de assinatura vem do rotate-secret, não do registro.
• As entregas são repetidas com backoff e um endpoint é suspenso após 10 falhas consecutivas — revise e reenvie pelo histórico de entregas.

FAQ

Quais eventos minha conta pode receber? Contas normais recebem os cinco eventos activity.*. user.register.v1 é somente para administradores, e webhook.test.v1 é apenas o evento de teste.

Como verifico que um webhook veio do SalesMind AI? Recalcule a assinatura a partir do corpo bruto e do cabeçalho Webhook-Timestamp, e compare com o cabeçalho Webhook-Signature. Consulte "Verificar a assinatura" acima.

Como obtenho o meu segredo de assinatura? O registro não o retorna. Chame o endpoint rotate-secret para obter um segredo novo e atualize sua cópia guardada imediatamente.

Por que meu endpoint foi suspenso? O SalesMind AI suspende um endpoint após entregas falhas demais seguidas — 10 por padrão. Conserte o seu servidor e retome o endpoint.

Posso reenviar um webhook que perdi? Sim. Use o endpoint de reenvio para enviar uma entrega anterior de novo como um novo evento.

Minha URL foi aceita mas não chegam eventos. Por quê? A verificação de HTTPS e URL pública ocorre no momento da entrega, não no registro. Uma URL incorreta é aceita no começo e depois falha na entrega. Verifique o seu histórico de entregas.