Primeiros passos com n8n

Este guia assume o caso mais comum: você quer reagir a eventos da Vensy dentro de um fluxo n8n (criar uma linha numa planilha quando um negócio é ganho, notificar um canal quando uma conversa for atribuída, etc.).

1. Crie o nó Webhook no n8n

Adicione um nó Webhook como gatilho do fluxo, com método POST. O n8n mostra duas URLs:

• URL de teste: só funciona enquanto você estiver com o editor aberto e escutando ("Listen for test event"). Use-a para cadastrar o endpoint na Vensy e mandar o primeiro evento de teste.
• URL de produção: fica ativa só depois que o fluxo é ativado (toggle no canto superior). É essa URL que deve ficar cadastrada na Vensy depois que o fluxo for para produção — trocar a URL de teste pela de produção é o erro mais comum nesse primeiro contato.

2. Cadastre o endpoint na Vensy

Pela UI: Configurações → Integrações e ferramentas → Webhooks, disponível para quem tem papel OWNER ou ADMIN no workspace. Informe:

• a URL do nó Webhook do n8n (teste, no primeiro momento);
• os eventos que você quer assinar, agrupados por família (ex.: marque deal.* inteiro, ou só deal.won);
• headers customizados, se o seu fluxo exigir um (ex.: um Header Auth adicional — veja a seção abaixo).

Ao salvar, o segredo é mostrado uma única vez. Guarde-o já — ele não aparece de novo, só é possível gerar um novo (o que invalida o anterior na hora). O mesmo cadastro pode ser feito pela API de gestão, com uma chave de API de escopo webhooks:manage.

3. Envie o evento de teste

Depois de criar o endpoint, use o botão "Testar" (ou POST /endpoints/:id/test pela API) para mandar um evento de exemplo, assinado de verdade, com "test": true no envelope. Confirme no n8n (no painel do nó Webhook, com "Listen for test event" ativo) que o payload chegou como esperado.

4. Filtre por tipo no fluxo

Um endpoint pode assinar vários tipos de evento ao mesmo tempo — o campo type do envelope é o que diferencia um message.received de um deal.won chegando no mesmo nó Webhook. Use um nó Switch ou If logo depois do Webhook, comparando {{ $json.type }}, para rotear cada tipo para o ramo certo do fluxo.

5. Evite loop com automações da Vensy

Se o seu fluxo n8n também escreve de volta na Vensy (ex.: atualiza um campo do contato via API pública), cuidado com o loop: essa escrita gera um novo evento (contact.updated), que volta para o seu webhook, que escreve de novo. Use o campo actor do envelope para distinguir origem:

{
  "actor": { "type": "api_key", "id": "...", "name": "n8n produção" }
}

Se o seu fluxo só deve reagir a mudanças feitas por humanos na UI (actor.type: "user") ou pelo contato (actor.type: "contact"), descarte eventos cujo actor.type seja api_key com o nome da própria integração, ou automation.

Autenticação adicional (opcional)

Além da assinatura Standard Webhooks — que é sempre enviada e deveria ser a sua verificação principal — você pode adicionar um Header Auth no nó Webhook do n8n (um header fixo tipo X-Minha-Chave: valor-secreto) e cadastrar esse mesmo header na Vensy como header customizado do endpoint. Isso é defesa em profundidade, não substitui verificar a assinatura.