Receber eventos do Vizus Chat por webhook

Webhook é o jeito de o Vizus Chat avisar o seu sistema quando algo acontece na conta, sem que o seu sistema precise ficar perguntando. Você cadastra uma URL e escolhe os eventos; a cada evento, o Vizus Chat faz um POST com um JSON para essa URL. É assim que um ERP, um n8n ou um CRM externo fica sabendo, na hora, que chegou mensagem, que uma conversa foi resolvida ou que um negócio foi ganho no funil.

Antes de começar

• A conta precisa estar no plano Profissional ou Escala. No Essencial, a criação de webhook é recusada (pela API, a resposta é 402 com a mensagem “Seu plano não inclui webhooks”). Veja Conhecer os planos. Contas cobradas direto pela Vizus seguem o que foi combinado no contrato.
• Você precisa ser administrador da conta.
• Tenha uma URL pública com HTTPS, pronta para receber POST com JSON. Se ainda não tem, ferramentas como o n8n (nó Webhook) geram uma em minutos.

Passo a passo

1. No menu lateral, abra Configurações → Integrações.

2. No card Webhooks, clique em Configurar.

   Os webhooks ficam em Integrações, junto das outras conexões da conta.

3. Clique em Adicionar novo Webhook.

   Você pode cadastrar mais de um webhook na mesma conta, cada um com a sua URL e os seus eventos.

4. Em URL do Webhook, cole o endereço que vai receber os eventos. Inclua um segredo seu na URL (veja Proteja a sua URL), por exemplo https://sua-api.com.br/vizus-webhook?token=SEU_SEGREDO.

5. Em Eventos, abra cada grupo (Conversas, Mensagens, Contatos, Caixa de Entrada, Kanban / Funil, Produtos, Agendamentos, Notas) e marque só os eventos de que o seu sistema precisa. O contador mostra quantos dos 27 eventos estão marcados.

6. Clique em Criar webhook.

   Neste exemplo: mensagem criada e as mudanças de etapa, ganho e perda do funil.

7. Confira: o webhook aparece na lista, com a URL e os Eventos Inscritos. Para mudar a URL ou os eventos, use o lápis; para apagar, a lixeira.

   A partir daqui, cada evento marcado gera um POST na sua URL.

Teste antes de ligar no sistema de verdade

Cadastre primeiro uma URL de teste (um site como webhook.site ou um nó Webhook do n8n em modo teste), mande uma mensagem para a caixa de entrada e confira o JSON que chegou. Depois troque pela URL definitiva.

Também dá para cadastrar pela API

O mesmo cadastro existe em POST /api/v1/accounts/{account_id}/webhooks, com url e subscriptions (a lista de eventos). Pela API há a opção incoming_only: com ela, os eventos de mensagem só chegam para mensagens recebidas do cliente, o que evita loop quando o seu sistema responde pela própria API.

Os eventos

O nome do evento chega no campo event do JSON.

Grupo	Evento	Quando acontece
Conversas	conversation_created	Uma conversa nova foi criada.
Conversas	conversation_updated	A conversa foi alterada (atribuição, etiquetas, atributos). Traz changed_attributes.
Conversas	conversation_status_changed	O status mudou: aberta, resolvida, pendente ou adiada.
Conversas	conversation_typing_on / conversation_typing_off	Alguém da equipe começou ou parou de digitar.
Mensagens	message_created	Mensagem nova, recebida ou enviada.
Mensagens	message_updated	Mensagem alterada, por exemplo o status de entrega.
Contatos	contact_created / contact_updated	Contato criado ou alterado.
Caixa de Entrada	inbox_created / inbox_updated	Caixa de entrada (canal) criada ou alterada.
Caixa de Entrada	webwidget_triggered	Um visitante abriu o chat do site.
Kanban / Funil	funnel_mapping_created	A conversa entrou num funil (negócio criado).
Kanban / Funil	funnel_stage_changed	O negócio mudou de etapa. Traz previous_stage e new_stage.
Kanban / Funil	funnel_mapping_updated	O negócio foi alterado sem mudar de etapa (valor, checklist, responsáveis).
Kanban / Funil	funnel_mapping_deleted	A conversa saiu do funil.
Kanban / Funil	funnel_deal_won / funnel_deal_lost	O negócio foi marcado como ganho ou perdido. Traz event_id para você não processar o mesmo desfecho duas vezes.
Produtos	conversation_product_created / _updated / _deleted	Produto da negociação lançado, alterado ou removido.
Agendamentos	conversation_appointment_created / _updated / _deleted	Agendamento criado, alterado ou removido.
Notas	conversation_note_created / _updated / _deleted	Nota da conversa criada, alterada ou removida.

Venda fechada no funil

Para disparar algo quando uma venda fecha (emitir pedido, mandar para o ERP, avisar o financeiro), use funnel_deal_won. É um evento próprio para o desfecho, mais simples de tratar do que acompanhar todas as mudanças de etapa.

Como chega o evento

Exemplo resumido de message_created:

{
  "event": "message_created",
  "id": 551203,
  "content": "Pode me mandar a proposta?",
  "message_type": "incoming",
  "sender": { "id": 7781, "name": "Maria Souza", "type": "contact" },
  "conversation": { "id": 1542, "inbox_id": 3, "status": "open" },
  "inbox": { "id": 3, "name": "WhatsApp Vendas" },
  "account": { "id": 1, "name": "Loja Exemplo" }
}

Exemplo resumido com dados fictícios.

E de funnel_deal_won (só os campos principais):

{
  "event": "funnel_deal_won",
  "event_id": "cfm_3310_deal_won_1759171200",
  "funnel_name": "Vendas B2B",
  "stage_label": "Fechamento",
  "deal_status": "deal_won",
  "deal_value": 1490.0,
  "won_reason": "Contrato assinado",
  "conversation": { "id": 1542 },
  "contact": { "id": 7781, "name": "Maria Souza" }
}

Dois números de conversa

conversation.id é o número que aparece no painel (#1542) e é o que vai nas rotas da API. Nos eventos do CRM há também conversation_id, que é um identificador interno. Para buscar a conversa pela API, use conversation.id.

Boas práticas para quem recebe

• Responda rápido com 200. A entrega tem tempo limite. Receba, guarde o evento numa fila e responda na hora; processe depois. Se a sua URL demorar ou cair, o evento pode se perder.
• Trate evento repetido. O mesmo evento pode chegar mais de uma vez. Nos desfechos do funil, guarde o event_id e ignore o que já foi processado. Nos outros, use o id do objeto junto com o event.
• Não dependa só do webhook. Se o seu servidor ficar fora do ar, o evento daquele momento pode não ser reenviado. Faça uma conferência periódica pela API (por exemplo, a cada hora, buscar as conversas e os negócios alterados) para pegar o que escapou.
• Assine só o que usa. Menos eventos é menos tráfego e menos código para manter. message_updated e os de digitação, por exemplo, chegam com muita frequência.

Proteja a sua URL

Qualquer pessoa que descubra a URL consegue mandar dados para ela. Para aceitar só o que veio do Vizus Chat:

• Coloque um segredo seu na URL, como ?token=um-valor-longo-e-aleatorio, e recuse no seu servidor qualquer chamada sem esse valor.
• Se a sua infraestrutura permitir, libere só os IPs de onde as chamadas chegam. Para saber quais são, fale com a Vizus.
• Use sempre HTTPS, para o segredo não trafegar aberto.

Deu errado?

• Não consegui criar o webhook. A conta pode estar no plano Essencial, que não inclui webhooks; veja a aba Cobrança em Configurações. Confira também se a URL é válida e começa com https://.
• O botão “Criar webhook” não habilita. Marque pelo menos um evento e informe uma URL válida.
• O webhook está cadastrado, mas nada chega. Confira se a URL está acessível pela internet (não pode ser localhost nem rede interna) e se o evento esperado está marcado. Faça uma ação que gere o evento, como mandar uma mensagem, e veja o log do seu servidor.
• Chegou o mesmo evento duas vezes. É esperado em alguns casos. Trate a repetição como em Boas práticas.
• Meu sistema responde pela API e entra em loop. Cada resposta gera um message_created. Ignore as mensagens com message_type diferente de incoming ou cadastre o webhook pela API com incoming_only.

Próximos passos

• Introdução à API
• Conhecer os planos