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:
- Reserve um caminho, como
/hotmart-purchase, no endpoint server side. - Configure um Client que aceite requisições somente nesse caminho e no formato esperado.
- Leia o cabeçalho de autenticação e compare com o hottok da conta.
- Verifique se o campo
idjá foi processado em armazenamento durável. - Reserve o
id, execute as tags e marque o resultado do processamento. - 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:
- Hottok errado interrompe o processamento.
PURCHASE_APPROVEDcria uma compra com transação, valor e moeda corretos.- A mesma notificação reenviada não cria outra compra.
- Um evento posterior da mesma transação segue o fluxo correspondente.
- 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.