Como mandar os eventos do CRM para outro sistema (webhooks)
Para que serve: avisar outro sistema (n8n, Make, Zapier ou o seu próprio) quando algo acontece no CRM, mandando os dados num POST para o endereço que você escolher.
O que você precisa
- Plano: qualquer um para os webhooks de Integrações → Técnico. A ação de webhook dentro de Automações é do plano Business.
- Permissão: gerente.
- Antes: o endereço (URL) do outro sistema que vai receber os dados.
Importante: Mensagem enviada (inbox) e Mensagem não enviada (inbox) valem para as mensagens do inbox (tela, API, robô, automação e cadência). Para campanha, use Mensagem de campanha enviada e Mensagem de campanha falhou. Resposta Recebida vale só para campanha e conta uma vez por contato em cada campanha. Contato criado (exceto importação em massa) não dispara para contatos que entram em lote, como importação de planilha e sincronização do WhatsApp.
Passo a passo
-
Vá em Configurações → Integrações e clique em Técnico.
Seção Técnico das Integrações -
No card Webhooks, clique em Adicionar Webhook. Preencha:
- Nome, por exemplo "Integração n8n";
- URL: o endereço que recebe os dados;
- Eventos: marque os eventos que você quer receber, como Negócio criado, Negócio ganho ou Formulário enviado.
Botão Adicionar Webhook
-
Deixe marcado Gerar chave secreta (HMAC) para o seu sistema conferir que o aviso veio mesmo do CRM. Clique em Criar Webhook.
-
A chave aparece uma única vez, na janela Copie a chave secreta agora. Copie, guarde no seu sistema e clique em Já copiei. O webhook aparece na lista como Ativo, com os eventos escolhidos e só o final da chave. Se perder a chave, clique em Gerar nova chave: a anterior para de valer na hora.
-
Clique no ícone de teste (Testar webhook). O CRM manda um aviso de teste com o evento
test. Confira se o seu sistema recebeu. -
Para conferir as entregas, abra Histórico de entregas no webhook (guarda os últimos 30 dias). Cada linha mostra Entregue, Tentando, Falhou ou Ignorado, o número de tentativas, o código HTTP de resposta e, enquanto tenta, a hora da próxima tentativa. Em entrega que não foi, clique em Tentar agora: ela sai de novo na hora, com assinatura nova, e a contagem de tentativas recomeça.
-
Para mandar o aviso só quando uma condição bate (plano Business), vá em Automações → Regras e crie uma regra com o gatilho que você quer, como Deal foi criado, Deal mudou de estágio ou Negócio fechado (ganho ou perdido), e a ação Enviar webhook (n8n/Zapier). Informe a URL e, se quiser, o "Secret HMAC (opcional)". Veja Como criar regras automáticas no funil.
Como o seu sistema recebe
- Webhooks de Integrações: POST em JSON com
id,event,timestampedata. Os cabeçalhos trazemX-Webhook-Event,X-Webhook-Id,X-Webhook-TimestampeX-Webhook-Attempt. - Formato do
data: em Contato alterado, Empresa (criada, alterada, desativada), Negócio alterado, Negócio apagado, Tarefa (todos) e Mensagem (recebida, enviada, não enviada), odataé o mesmo objeto que a API devolve. Contato criado, Negócio criado, Negócio mudou de etapa, Negócio ganho e Negócio perdido mantêm o formato antigo (valor em reais) e trazem o objeto da API no campoobject. Em Contatos mesclados,mergedContactIdé o contato que deixou de existir econtacté o que ficou. Campanha, formulário e agendamento têm formato próprio, descrito na documentação para desenvolvedores. - Assinatura: com a chave, vai o cabeçalho
Rumo-Signature: t=<hora do envio em segundos>,v1=<assinatura>. A assinatura é o HMAC SHA-256 de<t>.<corpo>com a sua chave. Use a chave como texto, do jeito que foi copiada. O seu sistema deve recusar avisos comta mais de 5 minutos do relógio dele: assim ninguém reaproveita um aviso antigo. Pode haver mais de umv1; aceite se qualquer um bater. - O cabeçalho antigo
X-Webhook-Signature: sha256=<assinatura>(HMAC SHA-256 só do corpo) continua saindo igual, para as integrações que já usam. Ele não leva a hora; nas integrações novas, useRumo-Signature. - O CRM espera a resposta por até 10 segundos. Se falhar, tenta de novo depois de cerca de 1 min, 5 min, 30 min, 2 h, 4 h, 7 h e 10 h: são até 8 tentativas, a última cerca de 24 horas depois da primeira. Cada tentativa sai com assinatura nova; o
iddo evento é o mesmo, então ignoreidrepetido. - O CRM garante o reenvio a partir do momento em que a entrega aparece no Histórico de entregas: ela fica guardada e sai de novo até confirmar, mesmo depois de um deploy. Nos milissegundos antes disso, o aviso fica anotado numa lista de pendências e é refeito sozinho por cerca de 2 horas. Essa lista depende de um serviço de apoio do CRM: se ele estiver fora do ar bem na hora em que algo muda e a gravação da entrega também falhar, o aviso se perde e fica só no nosso registro de erros. Isso vale também para Negócio apagado e Tarefa apagada quando o CRM não consegue ler o registro antes de apagar. Quem integra por API recupera o que faltou conferindo por
updatedSince, como explica a documentação para desenvolvedores. - Se o endereço passar 5 dias sem nenhuma entrega confirmada, o webhook é desativado sozinho e os gerentes recebem o aviso Webhook desativado no sino. Enquanto ele está desativado, os eventos que acontecem não ficam guardados para ele: ao ativar de novo, só chegam os eventos novos. As entregas que já esperavam nova tentativa viram Ignorado no histórico. Corrija o endereço e ative de novo.
- Telefone: o telefone do contato vai como está gravado no CRM. Número brasileiro vai só com dígitos, com o 55 e sem
+(ex.:5511999998888). Número de outro país, cadastrado com+e o DDI, vai em E.164, com o+(ex.:+14155550100). Contatos antigos podem estar em outro formato. - O que não gera aviso: renomear ou apagar uma tag e apagar um campo personalizado (em Configurações) mudam o que aparece em vários contatos e negócios de uma vez, mas não disparam Contato alterado nem Negócio alterado e não mudam a data de alteração desses registros. Se o seu sistema guarda tags ou campos personalizados, leia de novo os contatos e negócios pela API depois dessas mudanças.
- Ao gerar uma nova chave, a anterior para de valer na hora. Os avisos que o seu sistema recusar enquanto você troca a chave voltam nas próximas tentativas, já com a chave nova.
- Ação de webhook das Automações: POST em JSON com o gatilho e os IDs do negócio, da conversa, do contato e das fases. Espera até 5 segundos e não tenta de novo. Com a chave, a assinatura vai no cabeçalho
X-Revsend-Signature: sha256=<assinatura>.
Se algo der errado
| O que aparece | Por que acontece | O que fazer |
|---|---|---|
| "URL não permitida: endereços internos são bloqueados" | A URL aponta para um endereço interno (localhost, rede local) | Use um endereço público |
| "Limite de 10 webhooks atingido" | A conta já tem 10 webhooks | Exclua um que não usa |
| "Último erro: ..." no webhook | A última entrega falhou | Leia o erro, corrija o seu sistema e use Tentar agora |
| Marquei Contato criado (exceto importação em massa) e os contatos importados não chegaram | Importação em massa não dispara esse evento | É esperado. Contatos criados um a um disparam |
| Ignorado no histórico | A entrega já estava gravada, esperando nova tentativa, quando o webhook foi desativado (por você ou sozinho, depois de 5 dias sem entrega) | Ative o webhook de novo e clique em Tentar agora na entrega. Eventos que aconteceram com o webhook desativado não aparecem no histórico e não são reenviados |
| Aviso Webhook desativado no sino | O endereço passou 5 dias sem confirmar nenhuma entrega | Corrija o seu sistema, ative o webhook de novo e use Tentar agora nas entregas que falharam |
| "Esta entrega está sendo enviada agora ou já foi confirmada" | Uma tentativa daquela entrega estava em andamento | Espere alguns segundos e abra o histórico de novo |
O que este recurso não faz
- Não avisa contatos que entram em lote, como importação de planilha e sincronização do WhatsApp, nem mensagens antigas importadas ao conectar um canal.
- Não recebe dados de fora. Para receber leads de outro sistema, use as fontes de leads.
- Não deixa escolher quais campos vão no corpo do aviso.