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. A contagem parte do sistema que processou o pagamento, em vez de depender da página de obrigado abrir no navegador.

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.

Como o webhook 2.0 da Hotmart funciona

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, e a documentação do Webhook 2.0 recomenda validá-lo antes de tratar os dados (verificado em 17/10/2026).

O webhook é uma notificação, não uma base de consulta. 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. A própria Hotmart informa que os parâmetros estruturados de UTM não são repassados nos envios do Webhook e indica o xcod como alternativa (parâmetros UTM na Hotmart, verificado em 17/10/2026). 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 vira compra

O ponto de partida costuma ser PURCHASE_APPROVED. 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.

Se aprovado e completo dispararem a mesma conversão, uma única transação aparece duas vezes. Escolha uma das duas transições como a que cria a compra e documente. Para assinaturas, renovações também precisam ser separadas da primeira compra conforme o número de recorrência.

Uma regra inicial enxuta fica assim:

Evento recebidoAção de medição
PURCHASE_APPROVEDCriar a compra, depois da validação e do controle de reenvio
PURCHASE_COMPLETENão criar outra compra se a aprovação já criou
PURCHASE_REFUNDEDRegistrar reembolso e ajustar o relatório que suporta correção
PURCHASE_CHARGEBACKMarcar contestação para reconciliação financeira
PURCHASE_DELAYED ou PURCHASE_EXPIREDUsar no fluxo operacional, sem criar compra aprovada

Configurar o webhook no server GTM

Crie primeiro o endpoint que vai receber a requisição: HTTPS, um caminho reservado para essa integração e aceitação do JSON da versão escolhida. Depois, na conta Hotmart, abra Ferramentas, acesse Webhook, cadastre a URL e selecione só os eventos que o processo sabe tratar. A Central de Ajuda da Hotmart mostra essa tela, o envio de teste e o histórico.

No container, a peça que decide é o Client. A receita mínima que funciona:

  1. Reserve um caminho, como /hotmart-purchase, no endpoint server side.
  2. Use um Client de template próprio que só reconhece esse caminho. Assim que o caminho bater, ele chama claimRequest(), de forma síncrona e antes de qualquer trabalho assíncrono: a API de templates do server GTM diz que, com a requisição reivindicada, nenhum outro Client roda, e que a chamada lança exceção se vier depois de o Client retornar (verificado em 17/10/2026). Em seguida ele lê o cabeçalho com getRequestHeader('x-hotmart-hottok') e compara com o token da conta. Se não conferir, define o status 401 com setResponseStatus e chama returnResponse() sem chamar runContainer. Nenhuma tag dispara.
  3. Com o token válido, o Client tenta registrar o id da notificação num armazenamento fora do container, de forma atômica: uma transação no Firestore ou uma inserção com chave única num banco seu. Se o id já existe com sucesso, responde 200 e para.
  4. Só então o Client monta os dados do evento e roda o container. As tags enviam aos destinos.
  5. O registro guarda o estado por destino (recebido, enviado, falhou), para que uma falha parcial possa ser reprocessada sem repetir o que já foi enviado.
  6. Teste, publique e retire qualquer configuração de Preview usada no teste.

Sobre o token: o GTM server side não tem cofre de segredos. Uma variável Constante fica visível para quem edita o container, e o sandbox não oferece comparação em tempo constante. Se isso for um problema para a operação, valide o hottok antes do container, num Worker ou função na frente dele, e repasse ao sGTM só o que passou.

Fluxo da compra aprovada da Hotmart até um endpoint que valida o hottok, registra o identificador do evento e libera as tags.
O server GTM cuida do processamento e das tags. O registro durável do id impede que uma nova tentativa da mesma entrega conte outra compra.

Na Stape, o container 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, desde que você acrescente a checagem do hottok. A Stape é parceira afiliada da ATA. O artigo sobre o que é Stape e o que ela hospeda explica essa fronteira.

Ver uma entrega real no Preview

A tela de webhook da Hotmart tem nome, eventos e URL. Não há onde colocar o cabeçalho X-Gtm-Server-Preview, então uma entrega real não aparece no Preview do container. Há dois caminhos. O primeiro é copiar o JSON de uma entrega no histórico da Hotmart e reenviá-lo com curl, com o hottok e o cabeçalho de Preview atual. O segundo é o power-up sGTM Preview Header config da Stape, disponível a partir do plano Free e que pode ser limitado a um caminho de webhook ou a um IP (verificado em 17/10/2026). Desligue o power-up quando terminar.

O que o webhook não traz

O payload da Hotmart descreve a compra. Ele não traz o contexto do navegador do comprador, e é esse contexto que os destinos usam para atribuir:

  • Na Meta, um evento de site enviado pela API de Conversões exige o client_user_agent do visitante, segundo a página de parâmetros de cliente. fbc, fbp e o IP do visitante melhoram a correspondência.
  • No GA4, o Measurement Protocol identifica o usuário de um fluxo web pelo client_id, que precisa ser o mesmo gerado pela tag do Google no site para a compra ficar ligada à visita.

Esses valores precisam ter sido gravados na sua página, antes do checkout, e recuperados pela chave que viaja com o pedido. O guia do indexador entre a LP e o checkout mostra como. Nunca use o IP ou o user agent da conexão do webhook: são do servidor da Hotmart. O campo purchase.buyer_ip, quando presente no payload, é outro caso, tratado no FAQ abaixo. E não troque o action_source para escapar da validação.

Um mapeamento de referência:

Campo da HotmartMeta (CAPI)GA4 (Measurement Protocol)
purchase.transactionevent_id e custom_data.order_idtransaction_id
purchase.approved_date (ms)event_time = ms ÷ 1000, em segundostimestamp_micros = ms × 1000
purchase.full_price.value e .currency_value (ou os mesmos subcampos de purchase.price)custom_data.value e custom_data.currencyevents[].params.value e events[].params.currency
buyer.emailuser_data.em, normalizado e com SHA-256só com a coleta de dados fornecidos pelo usuário ativada na propriedade: SHA-256 do e-mail normalizado em user_data.sha256_email_address. Sem essa ativação, deixe o e-mail fora do GA4
(gravado na LP)client_user_agent, client_ip_address, fbp, fbcclient_id, session_id

Na Hotmart, full_price e price são objetos, não números. Segundo a referência do Webhook 2.0, full_price.value é o total pago pelo comprador, com taxas e juros, e price.value é o valor da oferta no momento da compra (verificado em 17/10/2026). Escolha um dos dois para o relatório e use o mesmo em todos os destinos. O e-mail no GA4 segue o guia de dados fornecidos pelo usuário e a ajuda do recurso, que pede a ativação na propriedade e dados com consentimento; sem ela, o GA4 não processa esses dados (verificado em 17/10/2026).

Os campos do payload e seus cuidados

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. 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 é a data de liberação da compra em milissegundos desde 1970-01-01 00:00:00 UTC, conforme a documentação. Um instante Unix não tem fuso. O destino precisa de conversão de unidade, não de fuso. Somar ou subtrair 3 horas desloca todos os eventos, e no sentido errado o horário cai no futuro.

Os dados de buyer só aparecem quando foram coletados no checkout e precisam de finalidade, acesso restrito e retenção definida. Não grave o payload inteiro por comodidade se a operação usa só uma parte.

CampoUso recomendadoCuidado
idChave da notificação recebidaRegistrar antes do envio evita processar a mesma entrega de novo
eventEscolher compra, reembolso ou contestaçãoNão mapear todos os estados como Purchase
purchase.transactionIdentificador do pedidoReaparece em mudanças posteriores da mesma transação
purchase.approved_dateHorário da aprovaçãoConverter a unidade (ms para s na Meta, ms para µs no GA4) sem aplicar fuso. A Meta aceita até 7 dias no passado; o GA4 aceita até 72 horas (verificado em 17/10/2026)
purchase.full_priceValor total e moedaConfirmar se o relatório quer total pago ou preço da oferta
buyer.email e buyer.checkout_phoneCorrespondência quando permitidaMinimizar, normalizar e aplicar o hash exigido pelo destino

As janelas vêm da página de evento de servidor da Meta, onde um event_time com mais de 7 dias derruba o lote inteiro, e do guia de envio do Measurement Protocol, que aceita eventos com até 72 horas de atraso. Elas pesam quando a fila do seu servidor para por dias. A mesma página do GA4 pede, em geral, que um evento do Measurement Protocol que vai ser processado junto com eventos da tag do site chegue em até 48 horas do evento original do navegador. A atribuição de sessão é mais estrita. O guia de casos de uso pede o session_id da sessão no evento, envio em até 24 horas do início dessa sessão e, se você sobrescrever timestamp_micros, um horário entre o começo e o fim dela (verificado em 17/10/2026). Um boleto pago quatro dias depois do clique chega como compra, com o horário real da aprovação, mas não volta para aquela sessão. Não recue o horário para forçar essa ligação.

Reenvios e idempotência

Trate toda entrega como repetível. Segundo a Central de Ajuda da Hotmart, posts com erro são reenviados automaticamente até cinco vezes, ou até o servidor dar uma resposta positiva, e o histórico guarda os eventos por até 60 dias, com reenvio manual (verificado em 17/10/2026). A mesma página avisa que, se a URL cadastrada apresentar erro, a Hotmart desativa a configuração automaticamente. Se as entregas pararem, confira primeiro se a configuração continua ativa.

O registro de idempotência fica na entrada, antes de qualquer tag, e o motivo é concreto. A documentação de deduplicação da Meta descreve o casamento entre um evento do navegador e um do servidor. Ela não promete descartar duas cópias enviadas pelo servidor, e para o método por fbp ou external_id diz que dois eventos consecutivos do servidor com a mesma informação não são descartados.

Em outubro de 2026, ao dimensionar a janela de reenvio do nosso próprio pipeline de eventos, adotamos essa leitura: um Purchase só de servidor reenviado pela CAPI deve ser tratado como duas compras.

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 notificações diferentes, com id próprio. O container sozinho não oferece um livro permanente de eventos. Mantenha o registro num banco ou serviço que sobreviva à execução.

O guia sobre deduplicação entre navegador e API de Conversões cobre o outro problema: duas rotas diferentes para o mesmo evento. Aqui, a duplicidade vem de duas tentativas de entregar a mesma notificação.

Teste de ponta a ponta

O teste 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.

Para conferir o lado da Meta sem depender da interface, o endpoint /stats do conjunto de dados na Graph API devolve contagens por hora, por nome de evento e por origem (navegador ou servidor). Num site próprio, em outubro de 2026, foi ele que confirmou entregas pela CAPI que o nosso log amostrado tinha perdido. Naqueles testes, as contagens apareceram cerca de uma hora depois; a Meta não publica um prazo, então espere antes de concluir que algo faltou.

Checklist de aceite:

  1. Hottok errado devolve 401 e nenhuma tag dispara.
  2. PURCHASE_APPROVED cria uma compra com transação, valor e moeda corretos.
  3. A mesma notificação reenviada não cria outra compra, nem quando duas entregas chegam ao mesmo tempo.
  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 uma vez.

Uma tag marcada como disparada no Preview 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 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.