Fluxo da utm_content até o webhook do checkout

O que precisa ser entregue

Todo pedido gerado no checkout deve carregar os parâmetros UTM da visita que originou a compra. O campo mais importante é a utm_content, porque é ela que identifica qual anúncio gerou o clique. Essa informação precisa voltar no payload de todos os webhooks do pedido (criado, aguardando pagamento, aprovado, reembolsado).

Como a utm_content é montada

Valores neste documento são exemplos ilustrativos.

As 7 etapas, do clique ao webhook

1. 1

   Anúncio configurado com parâmetros de URL

   Marketing · Meta Ads

   Em cada anúncio, no campo Parâmetros de URL, entra a string padrão abaixo. O Meta substitui as macros pelos valores reais do anúncio clicado.

   Copiar

   utm_source=FB&utm_medium={{placement}}&utm_campaign={{campaign.name}}|{{campaign.id}}&utm_term={{adset.name}}|{{adset.id}}&utm_content={{ad.name}}|{{ad.id}}

   Dado transportado: template com macros
2. 2

   Usuário clica e chega na página com a URL completa

   Navegador

   O Meta monta a URL final e acrescenta o fbclid automaticamente.

   Copiar

   https://pagina.exemplo.com.br/desafio?utm_source=FB&utm_medium=Instagram_Reels
   &utm_campaign=DESAFIO_OUT26|120210000000001
   &utm_term=PUBLICO_QUENTE|120211111111111
   &utm_content=AD07_video-depoimento|120212345678901
   &fbclid=IwAR2xYz...

   Dado transportado: utm_content na query string
3. 3

   Página de destino captura e persiste os parâmetros

   DEV · Front-end

   • Ler utm_source, utm_medium, utm_campaign, utm_term, utm_content, fbclid e gclid da URL.
   • Gravar em cookie first-party (domínio raiz .dominio.com.br, validade de 30 dias) e também em localStorage como reserva.
   • Regra de atribuição: último clique com UTM. Uma visita nova com UTM sobrescreve a anterior; uma visita sem UTM (direta, orgânica) não apaga o que já está salvo.
   • Opcional: guardar também a primeira origem (first_utm_content) para análise de primeiro toque.

   Dado transportado: cookie utm_content
4. 4

   Botão de compra repassa as UTMs para o checkout

   DEV · Front-end

   Todo link que leva ao checkout precisa ser "decorado" com os parâmetros salvos, porque o checkout costuma estar em outro domínio e não enxerga o cookie da página.

   Copiar

   // Executar ao carregar a página e antes de cada clique no CTA
   const KEYS = ['utm_source','utm_medium','utm_campaign','utm_term','utm_content','fbclid','gclid'];
   document.querySelectorAll('a[href*="checkout"]').forEach(a => {
     const url = new URL(a.href);
     KEYS.forEach(k => {
       const v = getStored(k); // lê do cookie / localStorage
       if (v && !url.searchParams.has(k)) url.searchParams.set(k, v);
     });
     a.href = url.toString(); // URLSearchParams já faz o encode do "|" (%7C)
   });

   Dado transportado: utm_content na URL do checkout
5. 5

   Checkout lê os parâmetros e grava no pedido

   DEV · Checkout (back-end)

   • Ao abrir, o checkout lê as UTMs da URL e mantém na sessão (o usuário pode recarregar ou trocar de etapa).
   • No momento em que o pedido é criado (antes do pagamento), gravar os valores em campos próprios do pedido: utm_source, utm_medium, utm_campaign, utm_term, utm_content, fbclid.
   • Fazer URL-decode antes de gravar (%7C → |). Coluna de texto com pelo menos 255 caracteres.
   • Os valores ficam congelados no pedido. Pix e boleto aprovados dias depois continuam com a origem do clique original.

   Dado transportado: pedido.utm_content (banco)
6. 6

   Mudança de status dispara o webhook

   DEV · Checkout (back-end)

   Em cada evento do pedido, o webhook envia um bloco tracking lido do próprio pedido, nunca da sessão atual. Upsell e order bump herdam o tracking do pedido principal.

   Copiar

   {
     "event": "order.paid",
     "order_id": "PED-2026-004812",
     "status": "paid",
     "payment_method": "pix",
     "created_at": "2026-10-14T10:32:05-03:00",
     "approved_at": "2026-10-14T10:34:51-03:00",
     "product": { "id": "desafio-primal", "price": 497.00 },
     "customer": { "email": "cliente@exemplo.com", "phone": "+5551999999999" },
     "tracking": {
       "utm_source":   "FB",
       "utm_medium":   "Instagram_Reels",
       "utm_campaign": "DESAFIO_OUT26|120210000000001",
       "utm_term":     "PUBLICO_QUENTE|120211111111111",
       "utm_content":  "AD07_video-depoimento|120212345678901",
       "fbclid":       "IwAR2xYz...",
       "src":          null,
       "sck":          null
     }
   }

   Dado transportado: tracking.utm_content no payload
7. 7

   Receptor identifica o anúncio

   UTMify / CRM / BI

   O sistema que recebe o webhook separa o valor no |: a parte da direita é o ID do anúncio no Meta. Com ele é possível cruzar a venda com gasto, criativo e conjunto, e calcular ROAS por anúncio.

   Resultado: venda → anúncio 120212345678901

Parâmetros que o checkout deve receber e devolver

Outras plataformas de anúncio. O mesmo campo serve para Google Ads (utm_content={creative}, ID do anúncio) e TikTok Ads (utm_content=__CID_NAME__|__CID__). O checkout não precisa tratar cada plataforma: basta guardar e devolver o texto como chegou.

Onde o rastreio costuma se perder

Caminho da utm_content