Webhooks na NexTags
As quatro formas de trocar dados com outro sistema (webhook de entrada, webhook de saída, requisição externa e API) e quando usar cada uma.
A NexTags troca dados com outros sistemas de quatro jeitos. Em dois deles, quem chama é o outro sistema: o webhook de entrada e a API. Nos outros dois, quem chama é a NexTags: o webhook de saída e a requisição externa do fluxo. Esta página mostra a diferença e ajuda a escolher. O passo a passo de tela de cada recurso está na Central de Ajuda; aqui fica a parte técnica.
Como funciona
| Forma | Quem chama quem | Onde fica no app | O que acontece |
|---|---|---|---|
| Webhook de entrada | O outro sistema chama um link da sua conta | Ferramentas › Webhooks de entrada | A NexTags acha o contato pelo telefone ou pelo e-mail (ou cria um novo), salva os valores recebidos nos campos e inicia um fluxo. |
| Webhook de saída | A NexTags chama um endereço do seu sistema | Ferramentas › Webhooks de saída | Quando um evento escolhido acontece na conta, como Etiqueta Aplicada, a NexTags avisa o endereço que está em Notificar este URL. |
| Requisição externa | O fluxo chama a sua API | Etapa Ações do fluxo › External API Request | Quando o contato chega à etapa, o fluxo chama a sua API e usa a resposta: guarda dados em campos ou manda mensagens e executa ações. |
| API | O seu sistema chama a NexTags | https://app.nextagsai.com.br/api, com a chave no cabeçalho X-ACCESS-TOKEN | O seu sistema cria e acha contatos, manda fluxos e mensagens, aplica etiquetas, preenche campos e move oportunidades. |
Webhook de entrada
Cada webhook de entrada tem um link próprio, copiado em Obter Link. O outro sistema manda um JSON para esse link. O link não pede a chave de API: quem tem o link consegue criar contatos e iniciar o fluxo, por isso ele é um segredo.
- O JSON precisa trazer o telefone ou o e-mail do contato. Basta um dos dois.
- Os valores vão para os campos do contato por caminhos JSONPath, como
$.cliente.email. - Depois de salvar os campos, a NexTags inicia o fluxo escolhido em Enviar Fluxo.
Detalhes em Webhook de entrada: receber dados de outro sistema e Mapear o corpo recebido para campos do contato. A tela, passo a passo: Webhooks de entrada.
Webhook de saída
O webhook de saída usa os mesmos eventos dos Acionadores e Ações, menos os de e-mail: contato novo, etiqueta aplicada ou removida, campo alterado, conversa atribuída, oportunidade criada ou movida, pedido novo e outros. A lista completa está em Todos os eventos dos acionadores. Na tela, a lista se chama Webhooks.
- O endereço precisa começar com
https://. Comhttp://, a tela mostra "The URL must start with https". - O formato do aviso (método, corpo e cabeçalhos) não aparece na tela. Confira o que chega num teste, antes de escrever o seu código. Veja Segurança, testes e novas tentativas.
A tela, passo a passo: Webhooks de saída: avisar outro sistema.
Requisição externa
Num ponto do fluxo, a ação External API Request chama o endereço que você escolher, com o método (GET, POST, PUT, PATCH ou DELETE), os cabeçalhos e o corpo que você montar. A resposta pode:
- preencher campos do contato, pelo Mapeamento de resposta;
- mandar mensagens e executar ações, quando o seu servidor responde no formato
{"messages": [], "actions": []}(o conteúdo dinâmico).
No quadro, a ação tem as saídas Sucesso e Falhado. Detalhes em Requisição externa: o fluxo chama o seu sistema. A tela, passo a passo: Requisição externa.
API
O seu sistema chama a API com a chave da conta no cabeçalho X-ACCESS-TOKEN. A chamada sai sempre do servidor, nunca do navegador nem do app do celular: lá, a chave ficaria exposta. Comece por Autenticação com a chave de API e veja todos os endpoints na Referência da API.
Quando usar
| Você quer… | Use |
|---|---|
| Que uma venda, um lead de formulário ou um evento de outro sistema inicie um fluxo | Webhook de entrada |
| Saber no seu sistema quando algo acontece na conta, como uma etiqueta aplicada ou uma oportunidade movida | Webhook de saída |
| Consultar ou gravar algo no seu sistema no meio da conversa, como o status de um pedido | Requisição externa |
| Montar no seu servidor as mensagens que o contato recebe, como a segunda via de um boleto | Requisição externa com conteúdo dinâmico |
| Que o seu sistema mande uma mensagem ou um fluxo, ou mova uma oportunidade, quando algo acontece lá | API |
| Ligar a NexTags ao Make, ao n8n, ao Zapier ou ao Pabbly | As quatro formas servem. Veja Usar a API no Make, n8n e Zapier |
Webhook de entrada ou API para criar contatos? O webhook de entrada não pede chave nem código do lado da NexTags: o outro sistema só manda o JSON. A API pede código, mas devolve o ID do contato e deixa o seu sistema decidir, caso a caso, qual fluxo mandar. Veja Criar ou atualizar um contato.
Dentro do fluxo, duas ferramentas ajudam a tratar os dados sem sair da NexTags: Obter dados de JSON, que tira valores de um JSON guardado num campo (Obter dados de JSON), e Executar código JavaScript, para cálculos curtos com os dados do contato (Executar código JavaScript). O código JavaScript não acessa a internet: para chamar uma API, use a requisição externa. Para avisar o Zapier, o Make ou o Pabbly num ponto do fluxo, há também o grupo Acionar (Acionar o Zapier, o Make e o Pabbly).
Boas práticas
Um webhook de entrada por origem
Crie um webhook de entrada para cada sistema ou formato de JSON, como "Compras da Hotmart" e "Leads do site". Cada um tem o seu link, os seus caminhos e o seu fluxo, e um erro num deles não afeta os outros.
Teste antes de ligar de verdade
Use o Testar Agora da requisição externa e um endereço de teste, como o Test URL do n8n, para ver o que chega e o que volta. Veja Segurança, testes e novas tentativas.
Guarde links e chaves fora do código
O link do webhook de entrada e a chave de API dão acesso à conta. Guarde os dois em variáveis de ambiente do servidor, como NEXTAGS_WEBHOOK_URL e NEXTAGS_API_KEY, e nunca num código que vai para o navegador.
Relacionados
Este conteúdo ajudou?
Obrigado! Sua resposta ajuda a melhorar a central.