# Segurança, testes e novas tentativas

> Como proteger o link do webhook de entrada, o endereço de saída e a requisição externa, como testar sem sistema pronto, tratar repetições e achar os erros.

Endereço: https://docs.nextags.com.br/webhooks/seguranca-e-testes/
Tipo: Referência

Atualizado em: 26/10/2026

Cada forma de troca de dados tem um ponto que precisa de cuidado: o link do webhook de entrada, o endereço que recebe o webhook de saída, o endpoint da requisição externa e a chave da API. Esta página reúne o que fazer em cada caso, como testar antes de ter o sistema pronto, como tratar o mesmo evento chegando duas vezes e onde ver os erros.

## O que proteger

| Recurso | O que dá acesso | O que fazer |
|---|---|---|
| Webhook de entrada | O link copiado em **Obter Link** | Guardar fora do código e longe do navegador. Se vazar, trocar. |
| Webhook de saída | O endereço em **Notificar este URL** | Usar `https://` e um caminho difícil de adivinhar. |
| Requisição externa | O endereço em **Request URL** | Mandar um segredo seu num cabeçalho e conferir no servidor. |
| API | A chave de API da conta | Guardar em variável de ambiente e chamar só do servidor. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/). |

## O link do webhook de entrada é um segredo

O link não pede chave: quem tem o link cria contatos com qualquer telefone ou e-mail e inicia o fluxo do webhook. Se o fluxo manda mensagens, o link nas mãos erradas faz a sua conta mandar mensagens para quem não pediu.

- Não ponha o link no HTML nem no JavaScript do site: quem abre a página vê o código. Mande os dados do formulário para o seu servidor, e o servidor manda para a NexTags. Veja o exemplo em [Exemplos: Hotmart, Kiwify, Shopify e formulários](https://docs.nextags.com.br/webhooks/exemplos-de-plataformas/).
- Guarde o link numa variável de ambiente, como `NEXTAGS_WEBHOOK_URL`, e não em repositórios, prints ou chamados abertos.
- A tela do webhook de entrada não tem campo para conferir a assinatura ou o token de quem envia, como o cabeçalho `X-HOTMART-HOTTOK` da Hotmart ou o parâmetro `signature` da Kiwify. Quem precisa dessa conferência recebe o webhook num servidor próprio, confere a assinatura e repassa os dados para a NexTags.

### Se o link vazar

O menu do webhook de entrada tem só **Obter Link**, **Renomear** e **Excluir**: não há um botão para gerar outro link para o mesmo webhook. Para trocar:

1. Em **Ferramentas** › **Webhooks de entrada**, clique em **Adicionar Novo** e crie outro webhook. Ele vem com um link novo.
2. Refaça a configuração: **Sample JSON**, os caminhos, os campos e o fluxo.
3. Troque o link no sistema que envia os dados e faça um envio de teste.
4. No webhook antigo, desligue o interruptor **Ativo** e depois clique em **Excluir**.

## Webhook de saída

- O endereço em **Notificar este URL** precisa começar com `https://`. Com `http://`, a tela mostra "The URL must start with https". Sem nada no começo, o app completa com `https://` ao salvar.
- O formato do aviso (método, corpo, cabeçalhos e se há assinatura) não aparece na tela. Antes de escrever o código, aponte o webhook para um endereço de teste e veja o que chega (veja [Como testar](https://docs.nextags.com.br/webhooks/seguranca-e-testes/#como-testar-sem-um-sistema-pronto)).
- Use no endereço um caminho difícil de adivinhar, como `https://seusistema.exemplo.com.br/webhooks/nextags/c8f2e1d94b7a`, e recuse no seu servidor os outros caminhos.
- Trate o aviso como um sinal. Se a decisão depende de dados confiáveis, como liberar um acesso, consulte o contato pela API antes de agir. Veja [Consultar contato](https://docs.nextags.com.br/referencia/contatos/consultar-contato/).

## Requisição externa

- Crie na aba **Cabeçalhos** um cabeçalho com um segredo seu, como `X-Segredo`, e confira o valor no servidor. Sem o segredo certo, responda `401`. Para não espalhar o segredo pelos fluxos, guarde num campo do bot: veja [Campos do bot](https://help.nextags.com.br/tutoriais/fluxos/campos-do-bot/).
- A NexTags manda o cabeçalho `X-USER-ID`, com o ID do contato, em toda requisição. Use para saber de que contato é a chamada, mas não como prova de origem: qualquer um consegue mandar esse cabeçalho. A prova é o seu segredo.
- Use um endereço `https://`, para o segredo e os dados do contato não viajarem abertos.
- O campo do sistema `{{page_api_key}}` traz a chave de API da conta. Mande essa chave só para a API da NexTags ou para sistemas seus, nunca para sistemas de terceiros. Veja [Campos do sistema](https://help.nextags.com.br/tutoriais/fluxos/campos-do-sistema/).

A conferência do segredo, com comparação em tempo constante:

**Conferir o segredo do cabeçalho**

```javascript
import { timingSafeEqual } from 'node:crypto';

// true quando o cabeçalho X-Segredo tem o valor da variável NEXTAGS_SEGREDO
export function segredoConfere(req) {
  const esperado = Buffer.from(process.env.NEXTAGS_SEGREDO ?? '');
  const recebido = Buffer.from(String(req.headers['x-segredo'] ?? ''));
  return esperado.length > 0 && esperado.length === recebido.length && timingSafeEqual(esperado, recebido);
}
```
```python
import hmac
import os

def segredo_confere(cabecalhos):
    """True quando o cabeçalho X-Segredo tem o valor da variável NEXTAGS_SEGREDO."""
    esperado = os.environ.get("NEXTAGS_SEGREDO", "").encode()
    recebido = cabecalhos.get("X-Segredo", "").encode()
    return bool(esperado) and hmac.compare_digest(esperado, recebido)
```
```php
<?php
// true quando o cabeçalho X-Segredo tem o valor da variável NEXTAGS_SEGREDO
function segredoConfere(): bool
{
    $esperado = (string) getenv('NEXTAGS_SEGREDO');
    $recebido = $_SERVER['HTTP_X_SEGREDO'] ?? '';
    return $esperado !== '' && hash_equals($esperado, $recebido);
}
```

O servidor completo está em [Requisição externa: o fluxo chama o seu sistema](https://docs.nextags.com.br/webhooks/requisicao-externa-no-fluxo/).

## Responda rápido e trate repetições

| Situação | O que fazer |
|---|---|
| O seu servidor demora para responder | Responda logo e deixe o trabalho pesado para depois, numa fila. O contato espera a resposta para seguir no fluxo, e o tempo limite da requisição externa não está publicado. |
| O mesmo evento chega duas vezes no seu sistema | Guarde um identificador de cada evento processado e ignore o que já viu. Não está documentado se a NexTags manda de novo um aviso que falhou: deixe o código pronto para receber o mesmo aviso mais de uma vez. |
| A plataforma manda o mesmo pedido duas vezes para o webhook de entrada | O contato não se repete (ele é achado pelo telefone ou pelo e-mail), mas o fluxo pode rodar de novo. No fluxo, aplique uma etiqueta, como "Boas-vindas enviadas", e confira com uma condição antes de mandar a mensagem. Veja [Etapa Condição](https://help.nextags.com.br/tutoriais/fluxos/condicoes/). |
| A outra plataforma desativa o webhook depois de erros | A Hotmart desativa a configuração e a Shopify apaga o webhook quando o endereço responde com erro; a Kiwify tenta de novo algumas vezes. Confira se o webhook de entrada está **Ativo** antes de reativar ou recriar do lado de lá. |

## Como testar sem um sistema pronto

| O que você quer ver | Como testar |
|---|---|
| O que a NexTags manda no webhook de saída ou na requisição externa | Aponte para o **Test URL** de um nó **Webhook** do n8n e clique em **Listen for test event**: o n8n mostra o que chegou. O Test URL só recebe enquanto espera o teste; depois, use o **Production URL**, com o workflow publicado. Outro serviço que mostra as requisições recebidas também serve. |
| A requisição externa, do envio à resposta | O **Testar Agora** da ação mostra o **Código do estado**, o **Corpo da resposta**, os **Cabeçalhos da resposta**, os **Cabeçalhos da solicitação** e o **Corpo da solicitação**. |
| O conteúdo dinâmico, sem servidor | A ferramenta [Devolver o JSON enviado (eco)](https://docs.nextags.com.br/referencia/ferramentas/devolver-o-json-enviado-eco/) devolve o JSON que recebe; o contrato da API diz que ela serve para gerar mensagens dinâmicas. Na requisição, use **POST** para `https://app.nextagsai.com.br/api/tools/echo`, o cabeçalho `X-ACCESS-TOKEN` com a chave e, no **Corpo** em **JSON**, o conteúdo dinâmico que você quer testar. Confira no teste se as mensagens chegam. |
| O webhook de entrada | Envie um JSON de teste com o cURL, como em [Webhook de entrada](https://docs.nextags.com.br/webhooks/webhook-de-entrada/), e confira o `Result:` de cada caminho depois de **Load sample JSON**. |
| O seu servidor, sem a NexTags | Simule a chamada com o cURL, com os cabeçalhos `X-Segredo` e `X-USER-ID`, como em [Requisição externa](https://docs.nextags.com.br/webhooks/requisicao-externa-no-fluxo/). |

Documentação do nó Webhook do n8n: [Webhook node](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.webhook/).

## Onde ver os erros

| Onde | O que mostra |
|---|---|
| **Fluxos** › aba **Registro de Erros** | As falhas da conta, com **Tipo**, **Descrição**, **Contato** e **Data**. A lupa pesquisa na lista. Veja [Registro de Erros: ler e resolver](https://help.nextags.com.br/tutoriais/fluxos/registro-de-erros/). |
| **Testar Agora**, na requisição externa | O código e o corpo da resposta, e o que a NexTags mandou. |
| Os campos `http_status_code` e `http_response_body` | O código e a resposta de cada chamada de verdade, guardados no contato pelo **Mapeamento de resposta**. |
| O editor do webhook de entrada | O `Result:` de cada caminho, sobre o **Sample JSON**. |
| O histórico da plataforma que envia | Os envios feitos para o link do webhook de entrada, como o **Histórico** da Hotmart e o **Ver logs** da Kiwify. |

Os erros comuns de requisição externa e de webhooks, com o que fazer, estão em [Erros de requisição externa, webhook e planilha](https://help.nextags.com.br/tutoriais/erros/erros-de-requisicao-externa/).