Segurança, testes e novas tentativas

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

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.
• 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).
• 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.

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

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

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);
}

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

Responda rápido e trate repetições

Como testar sem um sistema pronto

Documentação do nó Webhook do n8n: Webhook node.

Onde ver os erros

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.

Relacionados