Webhooks — Receber eventos do CRM - Central de Ajuda

O que são Webhooks

Webhooks outbound são notificações automáticas que o Vistum envia para uma URL da sua escolha quando um evento acontece no CRM. Por exemplo: quando um novo lead chegar, o Vistum pode avisar o seu n8n automaticamente, sem precisar ficar consultando a API a cada minuto.

Webhooks estão disponíveis a partir do plano Crescimento (5 webhooks); no Sob consulta são ilimitados. O plano Essencial não inclui esta função.

Criar um webhook

Acesse Configurações → API → Webhooks

No CRM, vá em Configurações → aba API → seção Webhooks.

Clique em Novo Webhook

Preencha:

URL: endereço HTTPS que receberá as notificações
Eventos: selecione quais eventos quer receber
Descrição: nome para identificar o webhook (ex: n8n-pipeline)

Copie o secret

O Vistum gera um secret de assinatura único. Guarde-o — você precisará dele para verificar que a notificação veio do Vistum.

Teste com Ping

Clique em Ping para enviar um evento de teste e confirmar que a URL está funcionando.

Eventos disponíveis

Evento	Quando é enviado
`lead.created`	Um novo lead foi criado via API
`contact.created`	Um novo contato entrou pelo WhatsApp
`message.received`	Uma mensagem foi recebida
`contact.tag_added`	Uma tag foi adicionada a um contato
`card.created`	Um card foi criado em um pipeline
`card.moved`	Um card foi movido entre etapas

O que acontece quando o webhook chega

Seu sistema receberá uma requisição POST com: Headers:

X-Vistum-Event: contact.created
X-Vistum-Delivery: whk_xxx
X-Vistum-Signature: t=1746666000,v1=abc123...
Content-Type: application/json

Body (exemplo):

{
  "event": "contact.created",
  "workspaceId": "wks_xxx",
  "timestamp": "2025-05-07T14:30:00.000Z",
  "data": {
    "contact_id": "cnt_xxx",
    "name": "João Silva",
    "phone": "5511999887766",
    "email": null
  }
}

Verificar que o webhook é legítimo

O header X-Vistum-Signature contém uma assinatura HMAC-SHA256 que prova que a notificação veio do Vistum. Sempre verifique antes de processar. Para detalhes técnicos de como validar, veja a documentação de verificação.

Ver histórico de entregas

Para cada webhook, você pode ver o histórico completo de envios:

Acesse Configurações → API → Webhooks
Clique no webhook desejado
Veja a aba Deliveries com status, código HTTP e tempo de resposta de cada envio

Reenviar manualmente

Se uma entrega falhou, você pode reenviá-la:

No histórico de deliveries, localize a entrega com falha
Clique em Reenviar

O que acontece quando a URL fica fora do ar

O Vistum tentará reenviar automaticamente com intervalos crescentes:

Tentativa	Aguarda
2ª	1 minuto
3ª	5 minutos
4ª	30 minutos
5ª	2 horas

Após 5 falhas consecutivas, o webhook é desativado automaticamente para não gerar mais tráfego desnecessário. Corrija o endpoint e reative nas configurações.

Rotacionar o secret

Se o secret for comprometido:

Acesse Configurações → API → Webhooks → [webhook] → Rotacionar Secret
Copie o novo secret
Atualize na sua aplicação

O Vistum passa a assinar com o novo secret imediatamente.

Começando

Usando o CRM

Automações

Integrações

Para Desenvolvedores

Permissões e Acesso

Conta e Plano

Privacidade e LGPD

Problemas Comuns

Suporte

Webhooks — Receber eventos do CRM

O que são Webhooks

Criar um webhook

Eventos disponíveis

O que acontece quando o webhook chega

Verificar que o webhook é legítimo

Ver histórico de entregas

Reenviar manualmente

O que acontece quando a URL fica fora do ar

Rotacionar o secret

​O que são Webhooks

​Criar um webhook

​Eventos disponíveis

​O que acontece quando o webhook chega

​Verificar que o webhook é legítimo

​Ver histórico de entregas

​Reenviar manualmente

​O que acontece quando a URL fica fora do ar

​Rotacionar o secret

O que são Webhooks

Criar um webhook

Eventos disponíveis

O que acontece quando o webhook chega

Verificar que o webhook é legítimo

Ver histórico de entregas

Reenviar manualmente

O que acontece quando a URL fica fora do ar

Rotacionar o secret