# 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.

Endereço: https://docs.nextags.com.br/webhooks/visao-geral/
Tipo: Conceito

Atualizado em: 26/10/2026

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](https://docs.nextags.com.br/webhooks/webhook-de-entrada/) e [Mapear o corpo recebido para campos do contato](https://docs.nextags.com.br/webhooks/mapear-campos/). A tela, passo a passo: [Webhooks de entrada](https://help.nextags.com.br/tutoriais/ferramentas/webhook-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](https://help.nextags.com.br/tutoriais/ferramentas/eventos-dos-acionadores/). Na tela, a lista se chama **Webhooks**.

- O endereço precisa começar com `https://`. Com `http://`, 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](https://docs.nextags.com.br/webhooks/seguranca-e-testes/).

A tela, passo a passo: [Webhooks de saída: avisar outro sistema](https://help.nextags.com.br/tutoriais/ferramentas/webhooks-de-saida/).

### 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](https://docs.nextags.com.br/webhooks/requisicao-externa-no-fluxo/). A tela, passo a passo: [Requisição externa](https://help.nextags.com.br/tutoriais/fluxos/requisicao-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](https://docs.nextags.com.br/comecar/autenticacao/) e veja todos os endpoints na [Referência da API](https://docs.nextags.com.br/referencia/).

## 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](https://docs.nextags.com.br/guias/make-n8n-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](https://docs.nextags.com.br/guias/criar-ou-atualizar-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](https://help.nextags.com.br/tutoriais/fluxos/dados-de-json/)), e **Executar código JavaScript**, para cálculos curtos com os dados do contato ([Executar código JavaScript](https://help.nextags.com.br/tutoriais/fluxos/javascript-no-fluxo/)). 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](https://help.nextags.com.br/tutoriais/fluxos/acionar-zapier-make-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](https://docs.nextags.com.br/webhooks/seguranca-e-testes/).

> **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.