Skip to main content

Documentation Index

Fetch the complete documentation index at: https://help.vistum.com.br/llms.txt

Use this file to discover all available pages before exploring further.

​
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 nos planos Growth (5 webhooks) e PRO (20 webhooks). O plano Essencial não inclui esta função.

​
Criar um webhook

1

Acesse Configurações → API → Webhooks

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

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)
3

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.
4

Teste com Ping

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

​
Eventos disponíveis

EventoQuando é enviado
lead.createdUm novo lead foi criado via API
contact.createdUm novo contato entrou pelo WhatsApp
message.receivedUma mensagem foi recebida
contact.tag_addedUma tag foi adicionada a um contato
card.createdUm card foi criado em um pipeline
card.movedUm 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:
  1. Acesse Configurações → API → Webhooks
  2. Clique no webhook desejado
  3. 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:
  1. No histórico de deliveries, localize a entrega com falha
  2. Clique em Reenviar

​
O que acontece quando a URL fica fora do ar

O Vistum tentará reenviar automaticamente com intervalos crescentes:
TentativaAguarda
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:
  1. Acesse Configurações → API → Webhooks → [webhook] → Rotacionar Secret
  2. Copie o novo secret
  3. Atualize na sua aplicação
O Vistum passa a assinar com o novo secret imediatamente.