Webhook custom: envie eventos pro pixel

A integração Custom recebe um webhook genérico de qualquer plataforma ou sistema próprio e envia o evento que você definir (venda, lead ou início de checkout) pros pixels do Facebook (Meta), Google Ads, GA4, TikTok, Pinterest, Taboola e OpenAI, pela API de Conversões de cada plataforma (server-side). O evento vai com os dados que o seu payload trouxer: valor, moeda, ID da transação, itens e dados do cliente (email, telefone, documento e endereço).

Um webhook enviado de servidor não traz os cookies do navegador. Por isso o Track Combo cruza o evento com a visita registrada pela Web Tag no seu site e completa com os identificadores de clique (fbp, fbc, gclid, ttclid) e as UTMs antes de enviar pros pixels. Se o seu sistema já guarda esses valores, você também pode mandá-los direto no payload.

# Quando Usar

A integração Custom é ideal quando:

• Sua plataforma não está na lista de integrações nativas
• Você tem um sistema próprio que envia webhooks
• Deseja conectar uma plataforma que o TrackCombo ainda não suporta nativamente

# Requisitos

• Plataforma com suporte a envio de webhooks
• Projeto criado no TrackCombo
• Web Tag instalada no site onde a conversão começa, pra o evento ser ligado ao clique no anúncio (ou os click IDs enviados no próprio payload, como mostrado abaixo)
• Pelo menos um pixel cadastrado no projeto com a API de Conversões ativa

# Passo a Passo

# 1. Adicione a Integração no TrackCombo

1. Abra seu projeto no TrackCombo
2. Vá em Integrações
3. Clique em + Nova Integração
4. Selecione Custom
5. Copie a URL do webhook gerada pelo TrackCombo

# 2. Configure na Sua Plataforma

1. Acesse as configurações de webhooks da sua plataforma
2. Adicione a URL copiada do TrackCombo como destino
3. Configure o método como POST
4. O payload deve ser enviado em formato JSON
5. Salve a configuração

# 3. Teste a Integração

1. Dispare um evento de teste na sua plataforma
2. No TrackCombo, acesse o projeto e vá na aba Eventos
3. Verifique se o evento apareceu corretamente
4. Confira se os dados do payload foram recebidos

# Formato do Payload

O TrackCombo aceita qualquer payload JSON. Se sua plataforma permite controlar o formato, envie no padrão canônico abaixo: assim o evento já é processado sem precisar de mapeamento adicional:

{
  "event_name": "purchase",
  "event_id": "PEDIDO-1",
  "data": {
    "user_data": {
      "email": "cliente@exemplo.com",
      "phone": "5511999999999",
      "doc": "12345678900",
      "name": "João Silva",
      "first_name": "João",
      "last_name": "Silva",
      "address": "Av. Paulista, 1000",
      "city": "São Paulo",
      "state": "SP",
      "zipcode": "01310-100",
      "country": "BR",
      "gender": "m",
      "birthday": "19900131",
      "user_id": "12345",
      "user_ip": "200.123.45.67",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
    },
    "tracking": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday",
      "utm_term": "curso-x",
      "utm_content": "criativo-a",
      "fbc": "fb.1.1700000000000.IwAR0...",
      "fbp": "fb.1.1700000000000.987654321",
      "gclid": "Cj0KCQjw...",
      "gcl_au": "1.1.123456789.1700000000",
      "ga": "GA1.2.123456789.1700000000",
      "ttclid": "E.C.P_xxxxx",
      "ttp": "01HABCDEF...",
      "epik": "dj0yJnU9...",
      "tbclid": "GiC0ABC123...",
      "tc_code": "tc_12345678",
      "src": "afiliado-x",
      "sck": "campanha-y"
    },
    "custom_data": {
      "transaction_id": "PEDIDO-1",
      "order_id": "PEDIDO-1",
      "value": 197.00,
      "currency": "BRL",
      "payment_type": "pix",
      "items": [
        {
          "item_id": "SKU-123",
          "item_name": "Curso X",
          "item_category": "cursos",
          "price": 197.00,
          "quantity": 1
        }
      ]
    }
  }
}

user_ip, user_agent e click IDs (fbc, gclid, ttclid…) são essenciais em webhooks server-side. Sem eles, o Facebook CAPI, Google Enhanced Conversions e TikTok Events API têm dificuldade de fazer o match com o anúncio que originou a conversão. Recupere esses valores dos cookies durante o checkout e envie no payload do purchase.

# Atribuição via tc_code (plano B quando não tem como propagar UTMs)

Se sua plataforma não permite propagar os UTMs/click IDs até o webhook (ex.: checkout externo que não aceita campos custom), use o tc_code como fallback. Ele é o código de atribuição interno do Track Combo, no formato tc_XXXXXXXX (8 dígitos).

O TrackCombo procura o tc_code em qualquer lugar do payload, não precisa estar em um campo específico. O servidor faz uma busca textual no JSON inteiro pelo padrão tc_ + 8 dígitos. Funciona se o código vier:

• Dentro de data.tracking.tc_code (lugar canônico)
• Concatenado em um campo qualquer: "order_note": "Pedido via tc_12345678"
• Dentro da URL de origem: "referrer": "https://meusite.com/?tc=tc_12345678"
• Em um campo customizado: "affiliate_code": "tc_12345678"
• Em qualquer outro lugar do JSON

Como obter o tc_code para enviar ao checkout: o código fica disponível no JavaScript via window.tcData.tracking.tc_code na sua landing page. Capture esse valor e propague para o checkout (via campo hidden no formulário, querystring, observation field do gateway etc.). Quando o webhook chegar ao TrackCombo com esse código embutido, a atribuição é reconstruída automaticamente.

Veja a lista completa de eventos e parâmetros aceitos em Eventos e Parâmetros: Referência.

Se sua plataforma envia o webhook em um formato fixo diferente desse, o TrackCombo permite mapear os campos via Custom Actions. Fale com o suporte para configurar.

# Pixels que funcionam com o webhook Custom

No webhook Custom, quem define o evento é você, pelo campo event_name do payload. Cada pixel recebe o evento canônico que você enviar com o nome que a plataforma de anúncio espera. Abaixo estão os três eventos mais usados: purchase (venda), lead (cadastro) e initiate_checkout (início de checkout).

# Facebook (Meta)

purchase vira Purchase, lead vira Lead e initiate_checkout vira InitiateCheckout na API de Conversões, com valor, moeda, ID da transação e dados do cliente. Precisa do Token de Conversão cadastrado no pixel. Veja como configurar o pixel do Facebook.

# Google Ads

Cada evento vira uma conversão do Google Ads só se houver um Conversion Label cadastrado no pixel pra aquele evento (purchase, lead ou initiate_checkout); sem label, o evento não é enviado. Veja como configurar o pixel do Google Ads.

# GA4 (Google Analytics)

purchase vira purchase, initiate_checkout vira begin_checkout e lead chega como lead pelo Measurement Protocol, com valor, moeda, ID da transação, itens e UTMs. Precisa do API Secret no pixel. Veja como configurar o GA4.

# TikTok

purchase vira CompletePayment e initiate_checkout vira InitiateCheckout na Events API do TikTok. Precisa do token de acesso no pixel. Veja como configurar o pixel do TikTok.

# Pinterest

purchase vira checkout, lead vira lead e initiate_checkout vira add_to_cart na API de Conversões do Pinterest. Precisa do token no pixel. Veja como configurar o pixel do Pinterest.

# Taboola

purchase vira make_purchase, lead vira lead e initiate_checkout vira start_checkout. Só vão pro Taboola os eventos de quem chegou por um anúncio do Taboola (com o clique tbclid registrado pela Web Tag ou enviado no payload). Veja como configurar o pixel do Taboola.

# OpenAI (anúncios no ChatGPT)

purchase vira order_created, lead vira lead_created e initiate_checkout vira checkout_started na Conversions API da OpenAI. Veja como configurar o pixel da OpenAI.

# Dados Traqueados

A integração aproveita todos os campos do padrão canônico que vierem no payload:

• Nome do evento e ID do evento
• Dados do cliente: email, telefone, documento, nome, endereço, cidade, estado, CEP, país, gênero, data de nascimento, ID do usuário, IP e navegador
• UTMs e identificadores de clique (fbc, fbp, gclid, gcl_au, ga, ttclid, ttp, epik, tbclid), além de tc_code, src e sck
• ID da transação, ID do pedido, valor, moeda, forma de pagamento e itens

# Dicas

• Use a aba Eventos do projeto para verificar exatamente o que está sendo recebido
• Se sua plataforma permite personalizar o payload, inclua campos como email, value, transaction_id para um traqueamento melhor
• Teste sempre com um evento real antes de confiar que a integração está funcionando

# Problemas Comuns

Como enviar conversões de um sistema próprio pro Facebook?
Crie uma integração Custom no seu projeto, cadastre o pixel do Facebook com o Token de Conversão e faça seu sistema enviar um POST em JSON pra URL do webhook, com event_name (ex.: purchase) e os dados do cliente. O evento chega no Facebook pela API de Conversões, sem depender do navegador do cliente.

O webhook Custom envia conversões pro Google Ads?
Sim, desde que o pixel do Google Ads tenha um Conversion Label cadastrado pro evento que você envia (por exemplo purchase ou lead). O gclid vem da visita registrada pela Web Tag ou do campo gclid do payload.

Qual event_name usar no webhook Custom?
Use o nome canônico do Track Combo: purchase pra venda, lead pra cadastro e initiate_checkout pra início de checkout (não begin_checkout). A lista completa está em Eventos e Parâmetros.

Eventos não aparecem no TrackCombo?

• Verifique se a URL do webhook está correta
• Confirme que o payload está em formato JSON
• Verifique se o método é POST
• Aguarde até 5 minutos para o processamento