Boosters

Webhooks no sGTM com o Data Client Wascer

Esta documentação descreve, passo a passo, como configurar o envio de webhooks de um sistema externo (CRM, CMS, plataforma de e-commerce, ERP etc.) para um contêiner Server-Side do Google Tag Manager (sGTM) hospedado na Wascer, como visualizar esses dados no debugger e como processá-los para uso em tags.

Os exemplos usam o caminho /order_created e o cenário “pedido criado no CRM”, mas você deve substituir esses valores pelo path e contexto do seu projeto (ex.: /lead_created , /payment_confirmed, /form_submitted ).

Sumário

  1. Pré-requisitos
  2. Visão geral do fluxo
  3. Etapa 1 — Enviar o webhook para o sGTM
  4. Etapa 2 — Visualizar os dados no debugger
  5. Etapa 3 — Processar o webhook com o Data Client Wascer
  6. Etapa 4 — Usar os dados em tags do sGTM
  7. Checklist de validação
  8. Solução de problemas comuns

1. Pré-requisitos

Antes de começar, garanta que você tenha:

  • Um contêiner Server-Side do GTM hospedado na Wascer, com plano ativo e URL pública acessível (ex.: https://sgtm.seudominio.com.br). Ainda não tem um servidor? Veja os planos disponíveis em wascer.com/en/pricing.
  • Acesso de edição ao contêiner Server-Side no GTM.
  • Acesso ao sistema de origem que vai disparar o webhook (CRM, CMS, plataforma de pagamento etc.) e permissão para configurar webhooks nele.
  • Acesso ao painel da Wascer, onde será configurado o Preview Header necessário para debugar os webhooks (recurso incluído em todos os planos).
  • O template Data Client Wascer baixado a partir do repositório oficial: github.com/soureiBR/Data-Client-Wascer.

💬 Precisa de ajuda na implementação? O time de suporte da Wascer auxilia na configuração inicial e em casos específicos. Acesse wascer.com para falar com a equipe.

2. Visão geral do fluxo

O envio de webhooks para o sGTM segue quatro etapas encadeadas:

  1. Sistema de origem dispara um HTTP POST para o sGTM na Wascer
  2. Data Client Wascer reivindica a requisição
  3. O evento fica disponível para Tags, Variáveis e Triggers
  4. Os dados são enviados para as plataformas de destino: Meta CAPI, GA4, Google Ads, Slack etc.

3. Etapa 1 — Enviar o webhook para o sGTM

3.1. Identifique o evento de origem

No sistema que vai disparar o webhook, escolha o evento que deseja rastrear. Exemplos:

  • Pedido criado no CRM/e-commerce
  • Lead qualificado mudou de status
  • Pagamento confirmado / estornado
  • Formulário enviado
  • Carrinho abandonado recuperado

3.2. Defina a URL de destino do webhook

A URL do webhook é composta por:

https://sgtm.seudominio.com.br/order_created
ComponenteValor de exemploO que é
URL do sGTMhttps://sgtm.seudominio.com.brURL pública do seu contêiner Server-Side na Wascer (domínio personalizado configurado no painel)
Path/order_createdIdentificador único deste webhook — usado depois para o Data Client Wascer reconhecer a requisição

💡 Boas práticas para o path:

  • Use nomes descritivos em minúsculas, sem espaços (/order_created, /lead_status_changed).
  • Use um path diferente para cada tipo de evento. Isso facilita criar um Data Client por evento e mantém o debug organizado.
  • Evite paths que possam colidir com rotas internas do GTM (não use /, /healthy, /gtm/*).

3.3. Configure o webhook no sistema de origem

A interface varia conforme o sistema (RD Station, HubSpot, Pipedrive, Shopify, WooCommerce etc.), mas os campos a preencher são sempre os mesmos:

CampoO que informar
URL / EndpointA URL completa montada no passo 3.2
Método HTTPPOST (padrão para webhooks; o Data Client Wascer também aceita GET se a origem não suportar POST)
Content-Typeapplication/json (recomendado)
Payload / BodyJSON com os campos do evento (ID do pedido, valor, e-mail, telefone, IDs de cookies etc.)
Headers customizadosOpcional — útil para autenticação (ex.: X-Api-Key)

Exemplo de payload JSON (cenário pedido criado — adapte aos seus campos):

{
  "event_name": "order_created",
  "order_id": "12345",
  "value": 299.90,
  "currency": "BRL",
  "customer": {
    "email": "cliente@exemplo.com",
    "phone": "+5511999999999",
    "first_name": "Maria",
    "last_name": "Silva"
  },
  "items": [
    { "id": "SKU-001", "name": "Produto X", "quantity": 1, "price": 299.90 }
  ],
  "fbp": "fb.1.1234567890.0987654321",
  "fbc": "fb.1.1234567890.IwAR_xyz",
  "client_user_agent": "Mozilla/5.0..."
}

⚠️ Importante: quanto mais identificadores do usuário você enviar (email, phone, fbp, fbc, ga_session_id, IP, user agent), melhor será a deduplicação e o match nas plataformas de anúncios.

4. Etapa 2 — Visualizar os dados do webhook no debugger

Por padrão, o debugger do sGTM não exibe requisições de webhook, porque webhooks são chamadas servidor-a-servidor e não carregam o cookie de preview que o GTM injeta no navegador.

Para resolver isso, é preciso copiar o X-Gtm-Server-Preview header do contêiner e injetá-lo através do painel da Wascer. O cabeçalho funciona como uma “credencial temporária” que diz ao sGTM: “todas as requisições que chegarem agora devem aparecer no modo preview”.

4.1. Ative o modo Preview no contêiner Server-Side

  1. Abra o contêiner Server-Side no GTM.
  2. Clique em Preview (canto superior direito).
  3. O debugger abre em uma nova aba e fica aguardando requisições.

4.2. Copie o cabeçalho X-Gtm-Server-Preview

  1. Dentro do debugger, localize o menu de opções (ícone de três pontos / menu adicional na barra superior).
  2. Selecione a opção que permite enviar requisições manualmente (Send requests manually / Enviar requisições manualmente).
  3. Um modal mostrará o valor do header X-Gtm-Server-Preview — uma string longa em base64.
  4. Copie o valor desse header.

📝 Nota: a localização exata desse menu mudou nas últimas versões do GTM. Se você não encontrar “Send requests manually”, procure por “Debug requests”, “Preview Headers” ou o ícone de configurações dentro do debugger. O valor a copiar é sempre identificado pelo nome X-Gtm-Server-Preview.

4.3. Injete o header no painel da Wascer

  1. Acesse o painel da Wascer e abra o contêiner sGTM correspondente.
  2. Localize a opção de Preview Header nas configurações do servidor.
  3. Cole o valor copiado no passo 4.2.
  4. Salve.

⏱️ Validade: o header é removido automaticamente pela Wascer após 1 hora por motivos de segurança. Se a janela de debug se estender, repita o processo de copiar/colar.

🔒 Boa prática: ao finalizar a depuração, remova manualmente o Preview Header no painel da Wascer para garantir que nenhum dado em produção continue sendo capturado no debugger.

4.4. Dispare o webhook e confirme no debugger

  1. No sistema de origem, force um disparo do webhook (criando um pedido de teste, alterando um lead etc.).
  2. Volte ao debugger do sGTM — a requisição deve aparecer na lista lateral de eventos.
  3. Clique sobre ela para inspecionar:
    • Request — URL, método, headers, body recebido.
    • Event Data — dados estruturados (depois que o Data Client Wascer processar — ver Etapa 3).

Se a requisição não aparecer, vá direto para a seção de solução de problemas.

5. Etapa 3 — Processar o webhook com o Data Client Wascer

Quando uma requisição chega ao sGTM, ela precisa ser reivindicada por um Client. Sem isso, nem o debugger consegue exibir os dados de forma estruturada, nem é possível usar os campos em tags.

Para isso, usamos o Data Client Wascer, um template customizado mantido pela Wascer que atua como mapper entre os dados da requisição e os dados do evento, com controle granular dos paths autorizados.

Funcionalidades principais do Data Client Wascer:

  • Validação de paths autorizados (ex.: /data, /spec, /top)
  • Suporte a múltiplos eventos por requisição
  • Headers CORS automáticos
  • Gerenciamento avançado de cookies (incluindo HttpOnly e renovação automática)
  • Respostas customizáveis (200, 301, 302, 403, 404)
  • Geração automática de client_id

5.1. Baixe o template do Data Client Wascer

  1. Acesse github.com/soureiBR/Data-Client-Wascer.
  2. Baixe o arquivo data-client-wascer.tpl (clique no arquivo no repositório e use Download raw file, ou clone o repositório completo).

5.2. Importe o template no sGTM

  1. No contêiner Server-Side, vá em Templates (menu lateral esquerdo).
  2. Na seção Client Templates, clique em Novo.
  3. No editor de template, clique no menu de opções (três pontos) e selecione Importar.
  4. Selecione o arquivo data-client-wascer.tpl baixado.
  5. Salve o template.

5.3. Crie um Client usando o Data Client Wascer

  1. Vá até a seção Clients (menu lateral esquerdo).
  2. Clique em Novo.
  3. Em Client Configuration, selecione o template Data Client Wascer.
  4. Dê um nome descritivo ao client — ex.: Data Client Wascer - Order Created.
  5. Em Accepted Path Settings, preencha o path definido na Etapa 1 — neste exemplo, /order_created. Se for usar mais de um path no mesmo Client, adicione todos.
  6. Configure as opções de resposta conforme necessário (status code, resposta JSON, gerenciamento de cookies).
  7. Salve o Client.

5.4. Configure prioridade (opcional, mas recomendado)

Se você tem outros clients no contêiner (GA4, Meta CAPI etc.), defina o Data Client Wascer com prioridade alta o suficiente para reivindicar webhooks antes que outro client tente. Geralmente, prioridade 100 é segura para webhooks customizados, já que GA4/CAPI clients vêm com prioridades mais baixas.

5.5. Publique uma versão de workspace (ou teste em preview)

  • Para validar em preview: basta salvar — não é necessário publicar.
  • Para usar em produção: publique uma nova versão do contêiner depois de testar.

5.6. Valide no debugger

  1. Volte ao debugger (com o Preview Header da Wascer ainda ativo).
  2. Dispare o webhook novamente.
  3. Na lista de eventos, a requisição agora deve aparecer reivindicada pelo Data Client Wascer.
  4. Clique no evento e inspecione a aba Event Data — você verá os campos do payload mapeados como variáveis acessíveis a tags.

6. Etapa 4 — Usar os dados em tags do sGTM

6.1. Crie variáveis do tipo Event Data

Para cada campo do payload que você quer usar em tags:

  1. Vá em Variables → New → Event Data.
  2. Em Key Path, informe o caminho do campo no payload. Exemplos:
    • order_id → captura order_id do JSON raiz.
    • customer.email → captura o e-mail dentro do objeto customer.
    • items.0.price → captura o preço do primeiro item.
  3. Dê um nome descritivo (ex.: evt - order_id) e salve.

6.2. Crie um trigger para o evento

  1. Vá em Triggers → New → Custom Event.
  2. Em Event Name, use o valor de event_name enviado no payload (ex.: order_created).
  3. Salve o trigger com um nome claro (ex.: Trigger - Order Created).

6.3. Configure as tags de destino

A partir daqui, o uso é igual ao de qualquer outro evento no sGTM. Cenários comuns:

DestinoTag a usarPara que
Meta (Facebook)Meta Conversions API (CAPI)Enviar conversões offline / server-side para o Pixel
Google AdsGoogle Ads Conversion Tracking / Offline Conversion ImportImportar conversões offline
GA4GA4 Server-SideRegistrar o evento no GA4
TikTokTikTok Events APIConversões para campanhas TikTok
Slack / TelegramHTTP Request ou tags específicasNotificar equipe sobre o evento
CRM secundárioHTTP RequestSincronizar dados entre sistemas

Em cada tag, mapeie os parâmetros (valor, moeda, IDs do usuário etc.) usando as variáveis Event Data criadas no passo 6.1, e associe o trigger criado no passo 6.2.

7. Checklist de validação

Antes de publicar em produção, confirme cada item:

  • ☐ O sistema de origem dispara o webhook com sucesso (status HTTP 2xx na resposta).
  • ☐ A URL do webhook usa HTTPS e aponta para o domínio correto do sGTM na Wascer.
  • ☐ O path do webhook está idêntico no sistema de origem e no Data Client Wascer.
  • ☐ O payload chega com Content-Type: application/json.
  • ☐ No debugger, a requisição aparece e é reivindicada pelo Data Client Wascer.
  • ☐ As variáveis Event Data retornam os valores esperados (não vazios / undefined).
  • ☐ O trigger dispara apenas para o evento certo.
  • ☐ As tags de destino executam com sucesso (status 2xx nas respostas das APIs externas).
  • ☐ O Preview Header foi removido do painel da Wascer após o fim dos testes.
  • ☐ Uma nova versão do contêiner foi publicada.

8. Solução de problemas comuns

O webhook não aparece no debugger

Possíveis causas:

  • Preview Header não foi colado no painel da Wascer / expirou — regenerar e injetar de novo.
  • URL do webhook está errada — confira protocolo (https://), domínio e path.
  • O sistema de origem está bloqueado por firewall / IP allowlist.
  • O webhook foi enviado antes de ativar o Preview no GTM.

Como diagnosticar: verifique nos logs do sistema de origem o status HTTP retornado pelo sGTM. Se for 2xx mas não aparece no debugger, o problema é certamente o Preview Header. Se for 4xx/5xx, é problema de roteamento ou configuração de servidor.

A requisição aparece, mas não é reivindicada por nenhum client

Possíveis causas:

  • Path do Data Client Wascer diferente do path enviado.
  • Data Client salvo no workspace mas o preview ainda não foi atualizado — feche e reabra o Preview.
  • Outro client está reivindicando a requisição com prioridade maior — ajuste as prioridades.

O Data Client Wascer reivindica, mas os campos vêm vazios

Possíveis causas:

  • Payload chegou com Content-Type incorreto (ex.: application/x-www-form-urlencoded em vez de application/json).
  • Estrutura do JSON é diferente do Key Path configurado nas variáveis — use a aba Request → Body no debugger para conferir o JSON cru e ajuste o Key Path.
  • Caracteres especiais / encoding quebrado — valide o JSON em um lint online.

Recebo 405 Method Not Allowed

O sGTM está rejeitando o método HTTP. Confirme que o sistema de origem está enviando POST (ou GET, se for o caso) e que o Data Client Wascer está configurado para aceitar esse método.

Recebo 200 OK mas a tag de destino não dispara

  • Verifique se o trigger está usando o event_name correto.
  • Confirme que a tag está associada ao trigger.
  • Olhe a aba Tags do evento no debugger para ver o motivo de cada tag ter disparado ou não.

O volume de requisições está alto e atingi o limite do plano

Cada plano da Wascer tem uma cota mensal de requisições. Se o volume de webhooks crescer, considere fazer upgrade — veja os planos disponíveis em wascer.com/en/pricing. Para volumes altos ou ambiente dedicado, fale com o time comercial.

Referências úteis

Este artigo foi útil?

Não encontrou o que procurava?

Nosso time responde em até 4 horas em dias úteis.

Falar com o suporte →