Como configurar webhooks de CRM

Webhooks são a ponte automática entre a Nuvia e seus sistemas externos (CRM, ERPs ou ferramentas customizadas). Em vez de sincronização manual ou puxada de dados, webhooks empurram eventos em tempo real — sempre que algo acontece na Nuvia (mensagem recebida, contato criado, campo atualizado), sua ferramenta externa é notificada instantaneamente e pode reagir.

Use webhooks para sincronizar dados bidirecionalmente entre a Nuvia e ferramentas como HubSpot, Salesforce ou RD Station, acionar fluxos automatizados em seu CRM ou gatilhar campanhas na Nuvia disparadas por eventos externos.

Disponível em: Menu lateral > Plataforma > Webhooks

Quem pode fazer: Proprietário e Administrador

Módulo: Plataforma (configurações globais)

O que você precisa antes de começar

Para configurar webhooks com sucesso, você precisa de:

Acesso de Proprietário ou Administrador na sua workspace Nuvia
URL válida do seu CRM ou sistema externo que receberá os eventos (deve estar acessível via HTTPS)
Documentação da API do seu CRM para saber quais campos e payloads ela espera receber
(Opcional) Token de autenticação ou API key se seu CRM exigir autenticação nos headers
Noção básica de REST APIs — webhook é apenas uma chamada HTTP POST com dados em JSON

💡 Dica: Se você não tem uma URL pronta, considere usar ferramentas como Webhook.cool ou RequestBin para testar e debugar antes de conectar ao seu CRM real.

Conceitos fundamentais

Termo	Significado
Webhook	Mecanismo de entrega automática de dados. Quando um evento ocorre na Nuvia, um POST HTTP é disparado para sua URL configurada.
Evento	Ação específica que dispara um webhook (ex.: mensagem recebida, contato criado). A Nuvia suporta 8 eventos diferentes.
Payload	Corpo do POST — dados estruturados em JSON que descrevem o evento e as entidades envolvidas.
URL de destino	Endpoint HTTPS onde a Nuvia envia o POST. Deve ser um domínio válido e acessível.
Header personalizado	Campo HTTP opcional (chave-valor) para autenticação ou metadados — exemplo: `Authorization: Bearer seu_token_aqui`.
Status	ATIVO = webhook funciona normalmente; INATIVO = webhook está pausado e não dispara eventos.

Criar um webhook

Passo a passo

1. Acesse a página de webhooks

Na sua workspace Nuvia, vá até Menu lateral > Plataforma > Webhooks.

2. Clique em "Criar webhook" ou "Novo webhook"

A forma de configuração será aberta com os seguintes campos:

3. Preencha os campos obrigatórios

Campo	O que é	Exemplo
URL	Endpoint HTTPS onde os eventos serão enviados. Deve ser uma URL válida e acessível.	`https://seu-crm.com/webhooks/nuvia`
Eventos	Selecione quais eventos disparam este webhook. Você pode escolher um ou vários.	MESSAGE_RECEIVED, CONTACT_UPDATED

4. (Opcional) Adicione headers personalizados

Se seu CRM exigir autenticação ou metadados, clique em Adicionar header e preencha:

Chave: nome do header (ex.: Authorization)
Valor: conteúdo do header (ex.: Bearer abc123xyz)

Repita para cada header que você precisar.

💡 Dica: Headers personalizados são úteis para:

Autenticação com token ou API key
Identificar a origem da requisição
Passar metadados específicos do seu negócio

5. Mantenha o status como ATIVO

Por padrão, webhooks novos nascem ATIVO. Deixe assim se quer que ele comece a funcionar imediatamente.

6. Revise e salve

Confirme que URL e eventos estão corretos. Clique em Salvar webhook.

Como saber se deu certo

Após salvar, a Nuvia enviará um teste automático para sua URL. Você saberá que funciona se:

Na interface: O webhook aparece na lista com status ATIVO, sem ícone de erro

No seu CRM/sistema: Você recebe um POST de teste (geralmente com um campo test: true ou event: WEBHOOK_TEST)

Nos logs: Seu servidor confirma recebimento com resposta HTTP 200 ou 2xx

⚠️ Se não funcionar:

Verifique se a URL está acessível (não está bloqueada por firewall)
Confirme que a URL começa com https:// (HTTP simples não é aceito)
Cheque se headers personalizados estão corretos (token expirado, chave mal formatada)
Consulte a seção "Erros comuns e soluções" abaixo

Entender os eventos disponíveis

A Nuvia oferece 8 eventos diferentes que você pode usar para disparar webhooks. Escolha os que fazem sentido para seu fluxo de trabalho.

Evento	Nome na interface	Quando dispara	Dados principais no payload
`MESSAGE_SENT`	Mensagem Enviada	Quando uma mensagem é enviada pela Nuvia (por campanha, agente de IA ou usuário)	Conversation ID, Contact ID, mensagem, canal, timestamp
`MESSAGE_RECEIVED`	Mensagem Recebida	Quando uma mensagem é recebida de um lead/contato	Conversation ID, Contact ID, conteúdo, canal, remetente
`CONVERSATION_CREATED`	Conversa Criada	Quando uma nova conversa é iniciada (primeira mensagem)	Conversation ID, Contact ID, canal, timestamp
`CONVERSATION_UPDATED`	Conversa Atualizada	Quando dados da conversa são alterados (status, assunto, atribuição)	Conversation ID, mudanças realizadas
`CONTACT_CREATED`	Contato Criado	Quando um contato é adicionado à base	Contact ID, nome, email, telefone, campos personalizados
`CONTACT_UPDATED`	Contato Atualizado	Quando qualquer campo do contato é modificado	Contact ID, quais campos mudaram e novos valores
`FOLLOWUP_SENT`	Follow-up Enviado	Quando um follow-up automático é disparado (por campanha ou agente)	Contact ID, Conversation ID, conteúdo, tipo de follow-up
`FIELD_UPDATED`	Campo Atualizado	Quando um campo personalizado na Nuvia é atualizado	Contact/Conversation ID, nome do campo, valor anterior e novo

💡 Estratégia: Comece com MESSAGE_RECEIVED e CONTACT_CREATED — são os mais úteis para manter seu CRM sincronizado.

Configurar headers personalizados

Headers personalizados permitem que você adicione informações de autenticação ou metadados aos seus webhooks.

Exemplo prático: Autenticação com Bearer Token

Seu CRM exige que toda requisição tenha um token nos headers. Aqui está como configurar:

1. Na forma de webhook, clique em "Adicionar header"

2. Preencha:

Chave: Authorization
Valor: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... (seu token real)

3. Salve

Agora toda requisição POST enviada pela Nuvia incluirá:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Exemplo 2: Multiple headers

Se você precisa passar várias informações:

Chave	Valor
`Authorization`	`Bearer token_aqui`
`X-Nuvia-Client`	`meu-crm-customizado`
`X-Request-ID`	`empresa-123`

⚠️ Segurança: Nunca compartilhe seus headers com outras pessoas. Tokens e API keys são sensíveis — guarde-os com a mesma cautela que senhas.

Ativar e desativar um webhook

Precisa pausar um webhook sem deletá-lo? Use o toggle de status.

Para desativar:

Localize o webhook na lista
Clique no toggle de status ou ícone de pausa
Mude para INATIVO
Salve

Quando INATIVO, eventos não disparam nenhuma requisição. Você pode reativar a qualquer momento sem perder configuração.

💡 Use-caso: Desative temporariamente durante manutenção no seu CRM ou enquanto debuga uma integração.

Editar um webhook existente

Pode mudar URL, eventos, headers ou status a qualquer momento.

1. Localize o webhook na lista de Webhooks

2. Clique em "Editar" (ícone de lápis ou botão)

3. Modifique os campos que precisa:

URL
Seleção de eventos
Headers personalizados
Status

4. Clique em "Salvar alterações"

A Nuvia envia um novo teste automático para validar a URL. Se houver erro, um aviso aparecerá na interface.

⚠️ Nota: Mudanças são aplicadas imediatamente. Eventos disparados depois da edição usarão a nova configuração.

Excluir um webhook

Quando você não precisa mais de um webhook:

1. Localize o webhook na lista

2. Clique em "Excluir" (ícone de lixeira ou botão de ação)

3. Confirme a exclusão

Um diálogo de confirmação aparecerá pedindo para você confirmar — isso é intencional, pois a exclusão não pode ser desfeita.

O que acontece quando você exclui

O webhook é permanentemente removido da Nuvia
Nenhum evento futuro será enviado para aquela URL
Dados já sincronizados no seu CRM permanecem intactos — você está apenas parando a entrega futura
Se você se arrepender, terá que criar um novo webhook com a mesma configuração

💡 Dica: Se você quer apenas pausar, desative o webhook (mude para INATIVO) em vez de deletar. Assim fica fácil reativar depois.

Usar webhooks para gatilho externo de campanhas

Além de sincronizar dados, webhooks também funcionam na direção oposta: seu CRM pode disparar campanhas na Nuvia.

Como funciona

Algo acontece no seu CRM (ex.: novo lead adicionado, oportunidade criada)
Seu CRM envia um POST HTTP para a Nuvia em um endpoint específico (/webhooks/trigger-campaign)
A Nuvia recebe a requisição e dispara automaticamente a campanha selecionada
A campanha envia mensagens aos contatos especificados

Pré-requisitos

Webhook de campanhas externas já deve estar configurado na Nuvia (isso é feito por seu Sales Ops ou tim técnico)
Seu CRM precisa ter a URL e credenciais para disparar webhooks na Nuvia (fornecidas durante setup)
A campanha desejada deve estar ATIVA na Nuvia

Saiba mais: Consulte o artigo Como criar e gerenciar campanhas para entender melhor campanhas por disparos externos.

Limites e regras

Limite	Detalhe
Um webhook por empresa	Você só pode criar um webhook de CRM por workspace. Se precisar enviar para múltiplos endpoints, configure diferentes eventos em um único webhook ou use um serviço de roteamento externo.
URL deve ser HTTPS	HTTP simples não é aceito. Sempre use `https://` para garantir segurança.
Timeout de entrega	Se o endpoint levar mais de 30 segundos para responder, a requisição é cancelada. > ⚠️ VERIFICAR COM PRODUTO: confirmar timeout exato
Retry automático	Se a entrega falhar (timeout ou erro 5xx), a Nuvia tenta novamente 3 vezes com backoff exponencial. > ⚠️ VERIFICAR COM PRODUTO: confirmar número e estratégia de retries
Headers personalizados	Máximo de 10 headers por webhook. Cada chave e valor devem ter no máximo 500 caracteres. > ⚠️ VERIFICAR COM PRODUTO: confirmar limites de headers
Eventos por webhook	Você precisa selecionar no mínimo 1 evento. Pode escolher até todos os 8 disponíveis em um único webhook.
Payload máximo	Cada POST pode ter até 10 MB de dados (estrutura JSON completa). > ⚠️ VERIFICAR COM PRODUTO: confirmar tamanho máximo

Erros comuns e soluções

Erro	Causa provável	Solução
"URL inválida"	URL não começa com `https://` ou tem formato inválido	Verifique que a URL está completa e acessível. Use `https://` sempre. Teste com ferramentas como curl ou Postman.
"Falha ao conectar"	Seu firewall bloqueia requisições saintes da Nuvia para o endpoint	Verifique com seu time de IT que o domínio da URL está desbloqueado. Considere usar um IP whitelist se seu CRM oferece.
"Erro 401 ou 403"	Headers de autenticação estão errados ou token expirou	Revise o token/API key nos headers. Verifique se o token ainda é válido. Teste com curl incluindo o header: `curl -H "Authorization: Bearer seu_token"`
"Erro 500 do servidor externo"	Seu CRM está retornando erro	Verifique os logs do seu CRM. Confirme que a estrutura do payload JSON está correta. Teste o endpoint com Postman usando um payload exemplo.
"Webhook foi deletado acidentalmente"	Ação irreversível	Recrie o webhook com a mesma URL e eventos. Não há backup — você terá que refazer a configuração.
"Webhook não está disparando"	Webhook está INATIVO ou nenhum evento está ocorrendo	Verifique status do webhook (ATIVO vs INATIVO). Confirme que os eventos selecionados realmente estão acontecendo na Nuvia (ex.: está alguém recebendo mensagens?). Cheque logs de entrega (se disponíveis).

Perguntas frequentes

P: Posso ter mais de um webhook para endpoints diferentes?

R: Não. Você está limitado a um webhook por workspace. Se precisa enviar dados para múltiplos sistemas, configure um único webhook com todos os eventos e use um serviço intermediário (como Zapier ou Make) para rotear para múltiplos destinos.

P: Como sei se um webhook foi disparado com sucesso?

R: Você saberá se receber um POST HTTP no seu endpoint. A Nuvia não mantém um "histórico" de disparos visível na interface (por enquanto). Recomendamos usar ferramentas como Webhook.cool para teste ou verificar os logs do seu CRM.

⚠️ VERIFICAR COM PRODUTO: confirmar se existe log de webhooks na interface que pode ser exibido

P: E se eu precisar de dados mais ricos no payload?

R: Descreva quais campos você precisa para seu time técnico (Sales Ops ou CTO). A Nuvia pode customizar payloads conforme necessidade — não faça requisições diretas, documente o caso de uso.

P: Posso triggerar múltiplas campanhas com um único webhook de CRM?

R: Não diretamente em um POST. Você precisaria de lógica customizada no seu CRM ou em um middleware para disparar múltiplas requisições para a Nuvia. Converse com seu Sales Ops sobre a arquitetura ideal.

P: Webhooks funcionam mesmo durante sincronização massiva (importação de contatos)?

R: Sim, mas com cuidado. Se você importar 10.000 contatos de uma vez, 10.000 eventos CONTACT_CREATED serão disparados. Isso pode sobrecarregar seu CRM. Para imports massivos, considere desativar temporariamente o webhook, fazer a importação, e depois reativar.

P: Qual é o melhor jeito de debugar um webhook que não funciona?

Use Webhook.cool ou RequestBin — crie um webhook público para visualizar requisições em tempo real
Configure seu webhook temporário da Nuvia apontando para esse serviço
Realize a ação que deve disparar o evento (enviar mensagem, criar contato)
Verifique se a requisição foi recebida e qual é a estrutura do payload
Depois, copie a URL permanente do seu CRM com a mesma estrutura esperada
Teste novamente com o endpoint final

P: Se eu desativar um webhook, os dados já sincronizados permanecem no CRM?

R: Sim, absoluto. Desativar um webhook apenas para a entrega futura. Dados que já foram enviados continuam no seu CRM — não são deletados retroativamente.

Próximos passos

Sua configuração de webhook está pronta! Agora:

Monitore os primeiros eventos para garantir que a integração está funcionando
Configure os headers personalizados se seu CRM exigir autenticação
Teste com diferentes eventos para entender o fluxo de dados
Documente em seu time qual webhook está ativo e para onde está enviando dados

Se encontrar problemas, consulte "Erros comuns e soluções" ou abra um ticket com seu time de suporte Nuvia.