Rastreamento Hotmart por webhook: venda aprovada no server GTM

Rastreamento Hotmart por webhook é o envio do status da transação diretamente da Hotmart para um endpoint controlado pela sua operação. Quando a compra muda para aprovada, a plataforma faz uma requisição HTTP com o evento e os dados do pedido. O servidor valida a origem, registra a entrega e transforma aquela aprovação em uma conversão. Assim, a contagem parte do sistema que processou o pagamento, em vez de depender da página de obrigado abrir no navegador.

O mecanismo resolve uma diferença que costuma ficar escondida no painel. Clique no botão de compra, boleto gerado e pagamento aprovado são momentos distintos. Uma tag de navegador pode observar o clique ou a visita à página final, mas não tem autoridade para afirmar que o dinheiro foi confirmado. O webhook tem essa mudança de status. Ele também avisa quando há reembolso, chargeback ou cancelamento, o que permite manter a medição próxima da situação real da venda.

O que é o rastreamento Hotmart por webhook?

É uma integração em que a Hotmart notifica uma URL sempre que ocorre um evento escolhido na configuração. Para vendas, a versão 2.0.0 envia um corpo JSON com event, id, datas e o objeto data, onde ficam produto, comprador e compra. O campo data.purchase.transaction identifica a transação. A autenticação chega fora do JSON, no cabeçalho HTTP X-HOTMART-HOTTOK. Segundo a documentação do Webhook 2.0 da Hotmart, esse token deve ser validado antes de tratar os dados recebidos. O webhook é uma notificação, não uma base de consulta. A própria Hotmart recomenda armazenar os eventos importantes e combinar Webhook com API quando o payload não traz tudo que a operação precisa. No rastreamento, ele funciona melhor como gatilho de um processo curto: autenticar, impedir reenvio duplicado, mapear a compra e enviar a conversão.

Isso é diferente de rastrear hotlink ou UTM. Os campos de origem ajudam a carregar contexto de aquisição quando estão disponíveis, mas não confirmam pagamento e não recriam um identificador de clique que nunca foi guardado. Primeiro vem a verdade da transação. A atribuição entra depois, com os identificadores coletados durante a jornada e ligados ao mesmo pedido.

Qual evento da Hotmart deve virar uma compra?

O ponto de partida costuma ser PURCHASE_APPROVED, porque ele informa que a compra foi aprovada. Use esse evento para criar Purchase na plataforma de mídia ou uma compra no seu sistema analítico. Não trate toda notificação como venda. PURCHASE_BILLET_PRINTED indica emissão de boleto, enquanto PURCHASE_DELAYED e PURCHASE_EXPIRED descrevem outros estados do pedido. PURCHASE_REFUNDED e PURCHASE_CHARGEBACK pedem uma correção própria, não outro Purchase. A lista oficial também inclui compra cancelada, completa e protestada. A escolha exata depende da regra financeira da operação, mas precisa ser explícita e documentada. Se aprovado e completo dispararem a mesma conversão, uma única transação pode aparecer duas vezes. Para assinaturas, renovações também precisam ser separadas da primeira compra conforme o número de recorrência e o desenho do produto. O nome do evento diz o que aconteceu; sua tabela de mapeamento decide o que o destino deve receber.

Uma regra inicial enxuta fica assim:

Evento recebido	Ação de medição
PURCHASE_APPROVED	Criar a compra, depois da validação e do controle de reenvio
PURCHASE_REFUNDED	Registrar reembolso e ajustar o relatório que suporta correção
PURCHASE_CHARGEBACK	Marcar contestação para reconciliação financeira
PURCHASE_DELAYED ou PURCHASE_EXPIRED	Usar no fluxo operacional, sem criar compra aprovada

Como configurar o webhook da Hotmart no server GTM?

Crie primeiro o endpoint que receberá a requisição. Ele precisa usar HTTPS, ter um caminho reservado para essa integração e aceitar o JSON da versão escolhida. Depois, na conta Hotmart, abra Ferramentas, acesse Webhook, cadastre a URL e selecione apenas os eventos que o processo sabe tratar. A Central de Ajuda da Hotmart mostra essa tela, o teste manual e o histórico das notificações. No container server GTM, um Client precisa reconhecer o caminho, reclamar a requisição e transformar os campos do corpo em dados de evento. As tags só disparam quando o Client conclui esse trabalho. Antes delas, valide o X-HOTMART-HOTTOK com comparação segura e consulte o registro de idempotência. Se a validação falhar, nada deve seguir para os destinos. O token fica em variável protegida, nunca no nome da URL ou exposto no navegador.

O fluxo completo tem seis passos:

1. Reserve um caminho, como /hotmart-purchase, no endpoint server side.
2. Configure um Client que aceite requisições somente nesse caminho e no formato esperado.
3. Leia o cabeçalho de autenticação e compare com o hottok da conta.
4. Verifique se o campo id já foi processado em armazenamento durável.
5. Reserve o id, execute as tags e marque o resultado do processamento.
6. Teste, publique o container e retire qualquer cabeçalho temporário usado no modo Preview.

Na Stape, o container server GTM fica hospedado num endpoint próprio e pode receber webhooks por um caminho específico. O Data Client é uma opção para transformar a requisição em dados de evento. Isso encurta a parte de infraestrutura, mas não remove as decisões da integração. O artigo sobre o que é Stape e o que ela hospeda explica essa fronteira. A Stape é parceira afiliada da ATA. Para uma implementação self-service, o callout de parceiro desta página traz o código MRPV20. Em projeto executado pela ATA, a conta é criada a preço cheio e o desconto entra no serviço.

Quais campos do payload precisam ser mapeados?

Comece pelo mínimo capaz de provar e reconciliar a venda. O campo id identifica a notificação e serve à idempotência. event informa a mudança ocorrida. data.purchase.transaction é a referência do pedido e deve alimentar o order_id ou campo equivalente no destino. Para valor e moeda, use os campos dentro de purchase, sem misturar preço da oferta, valor total pago e comissão. purchase.approved_date representa a liberação da compra, enquanto creation_date marca a criação do evento. Produto e oferta ajudam a separar linhas de negócio. Os dados de buyer só aparecem quando foram disponibilizados no checkout e precisam de finalidade, acesso restrito e retenção definida. E-mail ou telefone podem melhorar a correspondência na plataforma de mídia, mas devem seguir o tratamento exigido pelo destino. Não grave o payload inteiro por comodidade se a operação usa só uma parte.

Campo	Uso recomendado	Cuidado
id	Chave da notificação recebida	Guardar antes do envio evita processar a mesma entrega de novo
event	Escolher compra, reembolso ou contestação	Não mapear todos os estados como Purchase
purchase.transaction	Identificador do pedido	Reaparece em mudanças posteriores da mesma transação
purchase.approved_date	Horário da aprovação	Converter milissegundos no fuso esperado pelo destino
purchase.full_price	Valor total e moeda	Confirmar se o relatório quer total pago ou preço da oferta
buyer.email e buyer.checkout_phone	Correspondência quando permitida	Minimizar, normalizar e aplicar o tratamento exigido pelo destino

Como evitar conversões duplicadas nos reenvios?

Trate toda entrega como repetível. A Hotmart informa que posts com erro são reenviados automaticamente até cinco vezes, ou até o servidor dar uma resposta positiva. O histórico fica disponível por até 60 dias e permite reenvio manual. Por isso, o endpoint precisa ser idempotente. Antes de disparar qualquer tag, procure o campo id numa base durável. Se já existir com sucesso, responda sem criar outra conversão. Se for novo, reserve o registro, processe a ação e atualize o estado. purchase.transaction cumpre outro papel: liga aprovação, reembolso ou chargeback ao mesmo pedido. Não bloqueie um reembolso só porque a transação já apareceu numa aprovação; são eventos diferentes, com IDs próprios. O container server GTM não oferece sozinho um livro permanente de eventos. Para alta confiabilidade, use uma função, fila ou banco que sobreviva à execução e mantenha o registro fora do container.

O destino também deve receber purchase.transaction como identificador do pedido quando houver esse campo. Essa segunda camada ajuda a reconciliar relatórios, mas não substitui o controle na entrada. O guia sobre deduplicação entre navegador e API de Conversões cobre outro problema: duas rotas diferentes para o mesmo evento. Aqui, a duplicidade vem de duas tentativas de entregar a mesma notificação.

Como testar o rastreamento Hotmart de ponta a ponta?

O teste bom começa na ferramenta de Webhook, passa pelo Preview do server GTM e termina no destino. Use o envio de teste para confirmar URL, Client e leitura do payload. Depois faça uma transação controlada no produto certo, porque o teste sintético não prova valor, moeda nem dados opcionais do checkout. No histórico da Hotmart, abra a notificação e confira o payload e a resposta do endpoint. No servidor, confirme o caminho reclamado pelo Client, o resultado da autenticação, o id registrado e as variáveis montadas. No destino, procure a conversão pelo horário e pelo identificador da transação. Reenvie manualmente a mesma notificação e verifique que o contador não aumenta. Só então simule um estado posterior, quando o ambiente permitir, para confirmar que o sistema não transforma reembolso em uma nova compra.

Checklist de aceite:

1. Hottok errado interrompe o processamento.
2. PURCHASE_APPROVED cria uma compra com transação, valor e moeda corretos.
3. A mesma notificação reenviada não cria outra compra.
4. Um evento posterior da mesma transação segue o fluxo correspondente.
5. O histórico da Hotmart mostra resposta positiva e o destino recebe o evento esperado.

Uma tag marcada como disparada no Preview ainda não encerra o trabalho. Ela prova que o container executou. A validação termina quando a transação aprovada aparece uma vez no destino e continua reconciliável com a venda original. Se você quer essa implementação com autenticação, idempotência, mapeamento e teste de transação real, a Advanced Tracking Academy monta e valida o rastreamento com escopo fechado e documentação do fluxo.

Para uma nova fonte de mídia, o momento de ligar esse webhook à atribuição é antes do primeiro clique. O guia sobre por que a venda do checkout não marca na campanha mostra como criar um índice na LP, passá-lo no sck e recuperá-lo na aprovação. Para o caso do ChatGPT Ads, o artigo sobre o lançamento no Brasil explica o cadastro e a preservação do identificador do anúncio.