Webhooks de eventos
Visão geral
A Vensy avisa sua integração quando algo acontece no workspace.
A API pública e o CRM cobrem o puxar: sua integração pede dados quando precisa. Os webhooks de eventos cobrem o empurrar: você cadastra uma URL e a Vensy faz POST nela sempre que algo relevante acontece — uma mensagem chega, uma conversa é fechada, um negócio muda de etapa. É o caminho recomendado para ligar a Vensy no n8n, no Make ou em qualquer outro orquestrador.
Não confunda com os webhooks de automação
Esta seção é sobre a Vensy enviando eventos para você. Se o que você quer é o contrário — um formulário do seu site ou outro sistema disparando uma automação na Vensy — veja Conectar formulários e webhooks.
Conceitos
| Termo | O que é |
|---|---|
| Endpoint | Uma URL HTTPS cadastrada no workspace, com a lista de eventos que ela assina, um segredo e headers próprios. |
| Evento | Algo que aconteceu no workspace (message.received, deal.won...), representado por um envelope com id, type, occurredAt e os dados do recurso. |
| Entrega | Uma tentativa de POST de um evento para um endpoint. Um evento pode gerar várias entregas (uma por endpoint que o assina) e uma entrega pode ter várias tentativas (retries). |
| Tentativa | Uma chamada HTTP individual de uma entrega, com o status recebido (ou o erro) registrado no log. |
Garantias
- Pelo menos uma vez, sem ordem garantida. A mesma entrega pode chegar mais de uma vez (reenvio manual, retry que teve sucesso do lado do seu servidor mas a resposta se perdeu) e dois eventos podem chegar fora de ordem. Use
data.objecteoccurredAtpara decidir o estado final, nunca a ordem de chegada: compare ooccurredAtdo evento recebido com o que você já tem salvo e descarte o que chegar mais antigo. webhook-idé estável entre tentativas e entre endpoints — use-o para deduplicar (ex.: uma tabela de ids já processados, com TTL de alguns dias).- Nunca registra webhook sobre grupos do WhatsApp nem sobre backfill/importação histórica. Só eventos em tempo real de conversas 1:1 geram entrega. Uma importação em massa de contatos gera um evento por registro (
contact.createdrepetido), nunca um evento único de lote.
Limites
- 10 endpoints por workspace (ajustável pela Vensy, não autoatendimento).
- Só HTTPS. Não há IP fixo de saída — os nós do cluster são efêmeros — então não dá para autenticar por allowlist de IP; autentique pela assinatura.
- Disponível em todos os planos, sem necessidade de habilitar nada.
Próximos passos
Primeiros passos com n8n
Monte o fluxo mais comum: nó Webhook + endpoint na Vensy.
Assinatura e segurança
Verifique que a requisição realmente veio da Vensy.
Formato do evento
O envelope, o versionamento e exemplos reais.
Catálogo de eventos
Os 23 tipos disponíveis, por família.
Entregas, falhas e reenvio
Retentativas, desativação e a API de gestão.