Webhook da Kiwify e da Hotmart: como configurar e o que fazer quando o evento não chega

Quem integra checkout com tracker costuma tratar webhook como uma caixa preta: cadastra a URL, faz uma compra de teste, vê chegar e esquece. Funciona até o dia em que para de chegar — e aí não há onde olhar, porque ninguém entendeu o que estava acontecendo do outro lado.

Este artigo trata do evento em si: o que a plataforma dispara, quais eventos vale assinar, o que cada um deve provocar no seu relatório e, principalmente, como depurar quando o evento não chega. A montagem do identificador de clique e o mapeamento de campos por plataforma estão em postback da Hotmart, Kiwify e Monetizze; aqui o foco é o outro lado da linha.

Qual a diferença entre webhook e postback?

Webhook é o mecanismo de notificação da plataforma de vendas: ela guarda uma URL sua e chama essa URL sempre que um evento do pedido acontece. Postback é o nome que o mercado de afiliados dá a essa mesma chamada quando ela carrega o identificador de clique de volta e fecha a atribuição.

Ou seja: o webhook é o que a Kiwify ou a Hotmart dispara; o postback é o que o seu endpoint server-to-server faz com ele. Na configuração, você está sempre do lado receptor — não há consulta ativa, não há polling, não há API sendo lida. A plataforma avisa, você registra.

Quais eventos assinar e o que cada um deve fazer no tracker?

Assinar tudo é o erro mais comum. Cada evento assinado vira chamada, e chamada demais transforma o log num lugar onde ninguém encontra nada. A regra é simples: assine o que muda um número no relatório.

Três decisões precisam ser tomadas antes de ligar qualquer coisa, e elas definem a leitura do relatório inteiro:

Boleto e Pix gerados não são venda. Plataformas emitem um evento quando o pedido é criado e outro quando ele é pago. Contar o primeiro como conversão infla o número e destrói a leitura por campanha, porque a taxa de pagamento varia por criativo e por público.

Reembolso e chargeback voltam para a data da venda, não para a data do evento. Se o estorno cair no dia em que chegou, o dia da venda continua mostrando lucro que não existe e o dia do estorno mostra prejuízo de uma campanha que talvez nem esteja mais rodando. O raciocínio por trás disso está em reembolso, chargeback e conversão fantasma.

Assinatura tem mais de um evento de cobrança. Cada cobrança aprovada é receita nova ligada ao mesmo clique original. Quem trata só a primeira subestima o valor da campanha; quem trata todas precisa de id de transação distinto por cobrança.

Os nomes exatos dos eventos mudam entre Kiwify, Hotmart, Monetizze, Braip, Eduzz e Cartpanda, e mudam também ao longo do tempo dentro da mesma plataforma. Confira na documentação oficial da plataforma qual é a nomenclatura vigente antes de mapear — não copie nome de evento de tutorial antigo.

Como configurar o webhook passo a passo?

A ordem importa. Cadastrar a URL antes de ter o que casar produz um log cheio de eventos órfãos e a sensação falsa de que algo está quebrado.

1. Crie a oferta no tracker e gere o link de redirect que será usado no anúncio. É ele que cria o identificador de clique.
2. Monte a URL de destino com a macro do identificador no campo de rastreamento que a plataforma aceita no checkout. Confirme na documentação que esse campo volta no evento — campo que entra e não volta não serve para nada.
3. Gere a URL de recebimento no tracker, em HTTPS, com token de workspace ou no seu domínio de tracking próprio.
4. Cadastre essa URL no painel da plataforma de vendas, na área de integrações ou webhooks. O caminho de menu varia e é renomeado com frequência; procure pelo termo "webhook" na busca do painel em vez de seguir um passo a passo decorado.
5. Assine apenas os eventos da tabela acima, um a um, conferindo o nome atual de cada um na documentação.
6. Confirme o mapeamento dos três campos que importam: qual campo traz o identificador do clique, qual traz o valor e qual traz o id da transação. Os presets por plataforma cobrem o caso padrão; produtos com payload diferente pedem ajuste manual. A referência por plataforma está em integrações com Hotmart e Kiwify.
7. Dispare um teste pelo recurso do próprio painel ou com uma compra real de valor baixo, feita a partir do seu link de redirect.
8. Abra o log e confirme quatro coisas: o evento chegou, está casado com um clique, o valor está no campo certo e o id da transação foi lido.
9. Repita o teste para o evento de reembolso, se a plataforma permitir simular. É o evento que quase ninguém testa e o que mais causa divergência depois.

Como é o payload que chega?

O corpo do evento é JSON na maior parte das plataformas modernas. A estrutura varia, mas o conteúdo útil é sempre o mesmo conjunto: identificação do evento, identificação do pedido, valor, status e os campos livres de rastreamento que você preencheu no checkout.

Um exemplo genérico, apenas para ilustrar o formato:

{
  "evento": "compra_aprovada",
  "transacao": {
    "id": "TRX-90231",
    "status": "aprovado",
    "valor_bruto": 297.00,
    "valor_liquido": 261.36,
    "moeda": "BRL",
    "metodo_pagamento": "cartao"
  },
  "produto": {
    "id": "PRD-118",
    "nome": "Curso Exemplo"
  },
  "rastreamento": {
    "campo_livre_1": "8f2c1a7e-4b9d-4e11-9f30-2a5c7d10b4aa",
    "campo_livre_2": "camp-blackfriday_ad-07"
  }
}

Os nomes acima são ilustrativos. Não assuma que a sua plataforma usa essas chaves: abra um evento real no log e leia a estrutura que chegou. Uma diferença de aninhamento — o valor dentro de um objeto em vez de na raiz — é suficiente para o mapeamento ler vazio e a conversão entrar sem receita.

Algumas plataformas ainda enviam os dados como parâmetros na URL em vez de corpo JSON. Nesse caso, a URL cadastrada carrega macros da própria plataforma:

https://rastreio.seudominio.com.br/postback
  ?click_id={CAMPO_LIVRE}
  &event={STATUS}
  &value={VALOR}
  &txid={ID_TRANSACAO}
  &currency=BRL

As chaves em maiúsculo representam o que a plataforma substitui no momento do disparo. A nomenclatura dessas macros é específica de cada plataforma e está na documentação oficial dela.

Por que a deduplicação por id de transação é obrigatória?

Porque a plataforma reenvia — por desenho, não por defeito. Ela reenvia quando a primeira chamada falha, quando o status do pedido muda, quando alguém reprocessa a fila manualmente e quando o time dela corrige um incidente e redispara o backlog acumulado.

Se cada chegada virasse conversão, um reprocessamento de duas horas apareceria no relatório como um pico de vendas que nunca existiu, e você tomaria decisão de escala em cima dele. Por isso o critério é o id da transação: o mesmo id não gera segunda conversão, chegue ele duas ou vinte vezes.

Há um detalhe que vale exigir da sua implementação: quando chega um evento repetido com valor divergente, a conversão original deve ser preservada e o evento divergente registrado no log. Sobrescrever em silêncio significa descobrir semanas depois que um número mudou sozinho, sem rastro. A lógica completa de casamento e janela está em tracking e atribuição.

O webhook não chegou, e agora?

Este é o cenário que motiva o artigo. A depuração tem uma ordem, e ela é sempre da ponta da plataforma para a sua ponta.

Primeiro: a plataforma tentou enviar? O painel de webhooks da plataforma mostra o histórico de tentativas com código de resposta. Se não há tentativa registrada, o evento não foi disparado — ou você não assinou aquele evento, ou o webhook está configurado no nível errado. Em algumas plataformas o disparo é por produto e não por conta, então um produto novo entra sem webhook ativo. É a causa mais comum de "parou do nada" que na verdade é "nunca foi ligado para este produto".

URL cadastrada em http. Endpoints de recebimento exigem HTTPS. Uma URL em http:// pode ser aceita no cadastro e falhar no disparo, ou gerar um redirect que a plataforma não segue.

Resposta diferente de 2xx. Qualquer coisa fora da faixa 200 conta como falha: 301 e 302 incluídos, porque muitos clientes HTTP de webhook não seguem redirecionamento. Token errado devolvendo 401, caminho digitado com barra a mais devolvendo 404, erro interno devolvendo 500 — todos caem no mesmo balde.

Timeout. As plataformas dão poucos segundos de paciência. Se o seu endpoint processa antes de responder, uma lentidão momentânea vira falha registrada. O padrão correto é responder 2xx imediatamente e processar depois.

Fila pausada pela plataforma. Depois de N falhas consecutivas no mesmo endpoint — o número varia por plataforma — a fila é pausada ou o webhook é desativado automaticamente. O sintoma é o silêncio total começando algumas horas depois de um incidente que você nem percebeu. A reativação é manual, no painel.

IP bloqueado. Firewall, WAF ou regra de proteção contra bot na frente do endpoint podem barrar a origem da plataforma. O log da plataforma mostra a tentativa com erro de conexão ou 403, e o seu log de aplicação não mostra nada. Quando os dois lados discordam sobre a existência da chamada, olhe a camada de rede.

Payload em formato diferente do esperado. O evento chega, o endpoint responde 200 e nada aparece no relatório. Aqui não é problema de entrega, é de leitura: a plataforma mudou a estrutura, você mapeou um campo que hoje vem aninhado, ou o produto específico usa um formato distinto dos demais. O evento aparece no log como inválido, e a correção é no mapeamento.

Evento chegou casado, mas sem clique. Se o log marca o evento como órfão, a entrega está certa e o problema está na ida: o campo de rastreamento não foi preenchido na URL do checkout, ou o comprador entrou por fora do link de redirect. Órfão em volume alto é sintoma de cobertura, não de webhook.

Para cruzar esses eventos com o resto da operação ou exportar o histórico bruto e conferir fora do painel, o caminho é a API e exportação de dados. Termos que aparecem no meio da depuração estão no glossário.

O que conferir depois que estabilizar

Webhook funcionando não é webhook esquecido. Três hábitos evitam a maior parte das surpresas: conferir o log de eventos inválidos uma vez por semana, testar o fluxo inteiro sempre que subir um produto novo na plataforma, e revisar a assinatura de eventos depois de qualquer aviso de mudança na documentação da plataforma.

O rastreamento de vendas só é confiável enquanto os dois lados da linha continuam falando a mesma língua. A integração com a Hotmart, com a Kiwify ou com qualquer outra plataforma não é um estado permanente — é uma configuração que precisa sobreviver a mudanças que você não controla.