Tutorial: como configurar webhooks da Viniun

Os webhooks da Viniun avisam outro sistema na hora em que algo acontece no CRM: um lead novo, um imóvel publicado, uma proposta aceita, um contrato assinado. O seu site, a planilha do gerente, o sistema do contador ou uma automação no Zapier, Make ou n8n recebem o aviso sem ninguém copiar nada. Neste tutorial você cadastra o webhook, escolhe os eventos, confere a assinatura, testa e aprende a reativar um webhook que parou. Leva uns 10 minutos.

Quem pode fazer: quem tem permissão de editar o item API & Webhooks (em geral o dono ou o administrador). As telas são da conta de demonstração da Viniun, com dados fictícios. Na demonstração os webhooks ficam pausados e nenhum aviso é enviado.

A visão geral está no guia API, webhooks e integrações para imobiliária. Aqui é o passo a passo.

O que você precisa antes de começar

• O item API & Webhooks no menu Integrações.
• Um endereço que receba avisos: uma rota do seu site ou sistema, ou o endereço que o Zapier, o Make ou o n8n geram para você.
• O endereço precisa começar com https:// e responder em até 10 segundos.

Passo 1: abra a aba Webhooks

Em Integrações › API & Webhooks, clique na aba Webhooks. Cada cartão é um endereço que recebe avisos, com os eventos que ele assina. Se um webhook parou, o motivo aparece em vermelho no próprio cartão.

1. Webhooks — a aba. O número mostra quantos webhooks existem.
2. Novo webhook — abre o cadastro.
3. Webhook — o nome, o endereço que recebe e os eventos assinados.
4. Motivo da parada — aqui, 10 falhas seguidas com o erro 503 do outro sistema. O webhook se desativou sozinho.
5. O que chega no seu endpoint — o formato do aviso: o evento, a hora e os dados.

Passo 2: cadastre o nome e o endereço do webhook

Clique em Novo webhook. Dê um nome que diga quem recebe ("Site Exemplo", "Planilha do gerente") e cole o endereço que vai receber os avisos. A Viniun envia um POST com o aviso em JSON para esse endereço.

1. Nome — para você saber de quem é o webhook.
2. Endereço que vai receber — a rota do seu sistema, com https.
3. Assinatura — cada aviso leva o cabeçalho X-Viniun-Assinatura, que prova que veio da Viniun.

De onde vem o endereço no Zapier, Make e n8n

No Zapier, crie um Zap com o gatilho Webhooks by Zapier e a opção Catch Hook: ele mostra um endereço para copiar. No Make, use o módulo Webhooks › Custom webhook. No n8n, use o nó Webhook com o método POST e o endereço de produção. Cole esse endereço aqui. Depois, monte no Zapier, Make ou n8n o que fazer com o aviso: linha na planilha, e-mail, mensagem no grupo da equipe.

Passo 3: escolha os eventos e salve

Em Avisar quando, marque só o que esse destino precisa. Para um site próprio, o comum é lead.criado e os dois de imóvel. Para o financeiro ou o contador, transacao.concluida e contrato.assinado. Depois clique em Salvar.

1. lead.criado — um lead novo entrou, por qualquer canal. Vai com nome, telefone, e-mail, origem, imóvel e UTM.
2. imovel.publicado — um imóvel foi publicado. Vai com código, endereço amigável, título e o link da ficha na API do site.
3. imovel.despublicado — o imóvel saiu do ar pelo botão Despublicar. Bom para tirar a página do site.
4. Salvar — grava o webhook. A partir daí os avisos começam a sair.

Os eventos que disparam hoje: lead.criado, lead.etapa (mudou de etapa no funil), imovel.publicado, imovel.despublicado, proposta.aceita, contrato.assinado, transacao.etapa, transacao.concluida e automacao.disparada (só para o webhook escolhido numa regra das Automações). Atenção: lead.convertido, proposta.enviada e visita.agendada aparecem na lista, mas ainda não disparam. Não monte nada que dependa deles por enquanto.

Passo 4: confira a assinatura dos webhooks da Viniun

Cada aviso chega com três cabeçalhos: X-Viniun-Evento (o nome do evento), X-Viniun-Entrega (o número da entrega) e X-Viniun-Assinatura. A assinatura é um HMAC-SHA256 do corpo do aviso, em hexadecimal, feito com o segredo do webhook. Calcule do seu lado com o corpo exatamente como chegou e compare. Se não bater, recuse.

// Node.js (Express): use o corpo cru, antes de converter o JSON
import crypto from 'node:crypto';
app.post('/api/viniun-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const esperado = crypto.createHmac('sha256', process.env.VINIUN_SEGREDO)
    .update(req.body).digest('hex');
  if (esperado !== req.get('X-Viniun-Assinatura')) return res.sendStatus(401);
  const aviso = JSON.parse(req.body); // { evento, ocorrido_em, tenant, dados }
  res.sendStatus(200); // responda rápido; processe depois
});

<?php // PHP
$corpo = file_get_contents('php://input');
$esperado = hash_hmac('sha256', $corpo, getenv('VINIUN_SEGREDO'));
if (!hash_equals($esperado, $_SERVER['HTTP_X_VINIUN_ASSINATURA'] ?? '')) { http_response_code(401); exit; }
$aviso = json_decode($corpo, true);

O segredo é gerado pela Viniun quando o webhook é salvo: logo depois de clicar em Salvar, a janela Segredo deste webhook mostra o valor com o botão de copiar. Para ver de novo, abra Editar e salve. Guarde-o só no servidor. Zapier, Make e n8n podem ignorar a assinatura no começo, mas não deixe o endereço público à vista.

1. Um lead novo entrou — cada evento tem a sua página na seção Webhooks da documentação.
2. Cabeçalhos — o nome do evento e a assinatura HMAC-SHA256 do corpo.
3. Eventos — todos os nomes de evento possíveis.
4. Corpo — evento, data e hora, conta e os dados.
5. Resposta — qualquer resposta de sucesso (2xx) confirma. Outra resposta faz a Viniun tentar de novo.

A documentação fica em novo.viniun.com.br/docs/site-api, na seção Webhooks.

Passo 5: envie um aviso de teste

No cartão do webhook, clique no avião de papel. A Viniun manda na hora um aviso lead.criado de teste, com o lead "Lead de teste" e o campo "teste": true, e já com a assinatura. Se o seu endereço responder com sucesso, aparece "Enviado! Confira no seu sistema.". Se não, aparece "O seu endpoint não aceitou o envio de teste.".

1. Enviar teste — manda um aviso de teste agora. Ignore no seu sistema os avisos com "teste": true.
2. Editar — troca nome, endereço e eventos, e reativa um webhook parado.
3. Remover — apaga o webhook. O sistema deixa de avisar esse endereço.
4. Webhook — o cartão com o endereço, os eventos e o estado.

Passo 6: acompanhe falhas e reative o webhook

Se o seu sistema não responde com sucesso em 10 segundos, a Viniun tenta de novo: a primeira entrega sai em até 1 minuto e as novas tentativas vêm depois de 5 minutos, 30 minutos, 2 horas e 12 horas. Depois de 10 falhas seguidas, o webhook se desativa sozinho e o motivo fica no cartão. Corrija o problema do outro lado, clique em Editar, marque Reativar e salve.

1. Editar webhook — a mesma janela do cadastro.
2. Reativar — só aparece em webhook desativado. Marque a caixa e salve.
3. Salvar — reativa o webhook. Os avisos voltam a sair a partir dos próximos eventos.

Quais são as dicas e os erros mais comuns?

• Responda rápido. Devolva sucesso logo e processe o aviso depois. Mais de 10 segundos conta como falha.
• O mesmo aviso pode chegar duas vezes numa nova tentativa. Use o cabeçalho X-Viniun-Entrega para não processar repetido.
• Assinatura não bate? Calcule sobre o corpo cru. Converter o JSON e montar de novo muda o texto e a assinatura.
• Webhook não substitui o cache do site. Mudança de preço ou de fotos não gera aviso, e algumas saídas do ar (venda, importação) ainda não disparam imovel.despublicado. Atualize o site a cada 5 a 10 minutos também.
• Para receber leads de fora (o caminho contrário), o webhook não serve: veja o tutorial de receber leads.

Próximos passos

• Tutorial: API do site da Viniun
• Tutorial: receber leads de site externo
• Tutorial: cadência e automações do funil
• Tutorial: criar o site com Lovable
• Guia: API, webhooks e integrações para imobiliária