A venda chega sem o clique
O webhook de venda só carrega a origem se o click id tiver sido levado até o checkout. Parâmetros de texto livre se misturam com ids reais.
Projeto autoral · Tracking e atribuição
RedTrack Tracking Platform.
Middleware que liga o checkout, o RedTrack e a Meta. Cada venda vira uma conversão atribuída ao clique certo, uma única vez, mesmo com webhook duplicado, fora de ordem ou destino fora do ar.
Ambiente LAB 24/7 · fluxo validado de ponta a ponta com compras reais de teste
- testes automatizados passando
- 319
- endpoints de API
- 24
- classificações de evento
- 11
- telas no painel de operação
- 5
01
O problema
A plataforma de vendas sabe que alguém comprou. O tracker sabe de qual anúncio veio o clique. Sem uma ponte confiável entre os dois, a otimização de campanha trabalha com dado errado.
Webhooks repetem e chegam fora de ordem
Reentregas e reembolsos antes da aprovação acontecem. Contar duas vezes ou perder um evento distorce receita e atribuição.
Nem toda cobrança é uma conversão nova
Renovação de assinatura é receita, mas não é venda nova para o anúncio. Order bump, upsell, reembolso e chargeback precisam de tratamento próprio.
02
Como o fluxo funciona
Do clique no anúncio até o evento de conversão na Meta. Cada cor é uma plataforma; as etapas marcadas como "Este projeto" são código próprio.
RedTrackCheckoutMetaEste projeto
- 1RedTrack
Clique no anúncio
O domínio de tracking do RedTrack registra o clique e gera um click id de 24 caracteres.
Passa adianteclick id na URL - 2Este projetoRedTrack
Captura no navegador
Script próprio lê o click id (query e cookies), dispara InitiateCheckout e marcos do vídeo (play, 1, 3, 5 e 10 min) com deduplicação. Falha de rede nunca bloqueia a ida ao checkout.
Passa adianteeventos + click id de checkout - 3Checkout
Checkout com origem
O click id segue nos parâmetros de origem da plataforma de checkout até a compra. A Hotmart é a integração em uso hoje.
Passa adiantewebhook de venda com o click id - 4Este projeto
Webhook: validar, classificar, gravar
Token comparado em tempo constante, schema validado com Zod, dados pessoais redigidos, evento classificado e gravado de forma idempotente. A resposta sai antes de qualquer chamada externa.
Passa adianteevento classificado - 5Este projetoRedTrack
Postback servidor a servidor
Conversão enviada ao RedTrack com valor, tipo e id da transação. Timeout, 429 e 5xx entram em retry com backoff exponencial. Erro 4xx não é repetido.
Passa adianteconversão atribuída ao clique - 6RedTrackMeta
Conversions API
O RedTrack repassa o evento para a Meta. Compra, order bump e upsell saem como eventos distintos, com o id da transação como chave de deduplicação.
03
O que foi construído
Idempotência de verdade
Id do evento como chave primária e par transação + evento único. Duplicatas vão para uma tabela própria. Reentrega de um evento que tinha falhado refaz o envio sem criar linha nova.
Classificação de eventos financeiros
Compra, order bump, upsell, downsell, renovação, reembolso, chargeback, cancelamento, atraso e desconhecido. Renovação entra na receita e não é enviada como conversão nova.
Enriquecimento depois do ACK
Quando falta informação de recorrência, o backend consulta a API de pagamentos da plataforma depois de responder ao webhook. O merge só preenche campos vazios, divergência vira conflito para revisão.
Mapeamento de ofertas no banco
CRUD com optimistic locking, trilha de auditoria append-only e snapshot em memória que falha fechado no boot. Rollback por feature flag, sem migração destrutiva.
Nunca reinterpretar em silêncio
Evento já enviado não é reenviado nem reclassificado automaticamente. Mudança de mapeamento depois do envio vira conflito visível no painel, com prévia antes de reprocessar.
Financeiro reconciliado
Bruto, reembolsos, chargebacks e líquido calculados a partir dos eventos. Quando o histórico está incompleto, o líquido fica nulo em vez de um zero inventado.
Segurança
Sessão com cookie HttpOnly e token CSRF, rate limit no login e no admin, CSP restritiva, 404 opaco e painel fechado em produção sem token. Respostas e logs sem dados pessoais.
Operação e observabilidade
Health e readiness, contadores de duplicatas e retries, alertas de backlog, taxa de falha e ausência de webhook. Migrations aditivas e idempotentes, deploy com testes como gate.
04
Painel de operação
Interface em HTML, CSS e ES modules servida pelo próprio backend, sem framework e sem bundler. As telas abaixo usam dados sintéticos.
05
Decisões e trade-offs
Uma fonte de verdade por assunto
A plataforma de checkout é a verdade financeira, o banco é a verdade operacional, o RedTrack cuida da atribuição e a Meta só de otimização.
Sem fila e sem Redis
O volume não justifica. Retry e enriquecimento rodam no próprio processo, em instância única. O limite dessa escolha está documentado.
Dois click ids, de propósito
O clique da página recebe os eventos de engajamento. O clique de checkout recebe a compra. Separar os dois evita atribuir venda ao evento errado.
A Meta fica atrás do RedTrack
O backend não chama a Conversions API direto. Um único caminho de envio reduz o risco de evento duplicado na Meta.
IA apenas como consulta
O painel pode pedir a um modelo uma sugestão de mapeamento para oferta desconhecida. A sugestão nunca grava nada. O envio continua determinístico.
06
Estado atual, sem maquiagem
Validado
- Compra, order bump e upsell reais de teste, do clique ao evento na Meta
- Idempotência, retry de postback e reprocessamento de oferta não mapeada
- Marcos de vídeo e InitiateCheckout com deduplicação no navegador
- Três campanhas em paralelo sem contaminação de atribuição
- Infra 24/7 com Postgres, deploy bloqueado por typecheck e testes
Ainda não
- Nenhum cliente em produção: o ambiente é de laboratório
- Downsell implementado, mas nunca testado com transação real
- Instância única: sessão, rate limit e snapshot ficam em memória
- Código privado, por conter configuração de operação
Stack
Node.jsTypeScriptFastifyZodPostgreSQLSQLiteVitestRenderRedTrackMeta CAPIHotmart API
Quer ver o código ou conversar sobre o projeto?
O repositório é privado. Mostro a arquitetura e o código em uma conversa.
Projeto independente. Não é afiliado nem endossado por RedTrack, Hotmart ou Meta. Nomes e marcas pertencem aos respectivos donos.