Integrar com Webhook Custom

Use a integração Custom para conectar qualquer plataforma ao TrackCombo via webhook genérico.

# 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
• Container criado no TrackCombo

# Passo a Passo

# 1. Adicione a Integração no TrackCombo

1. Abra seu container 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 container e vá em Logs
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": "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.

# Dicas

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

# Problemas Comuns

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