Vendas do checkout

Webhook de vendas: qualquer plataforma no TraceClose

Atualizado em 12 de outubro de 2026

Use este caminho quando a sua plataforma não está na lista de integrações prontas (Hotmart, Kiwify, Eduzz e Shopify): outro checkout, um sistema próprio ou uma planilha. Você precisa de uma ferramenta de automação que faça uma chamada HTTP ou de alguém que escreva algumas linhas de código.

Passo a passo

1. Crie a conexão

   Em Configurações › Integrações, clique em Nova conexão e escolha Webhook de vendas (qualquer plataforma). É a mesma conexão do lead do site: serve para leads e vendas.

2. Gere e guarde o segredo

   Clique em Gerar segredo e em Copiar segredo. Guarde na ferramenta que vai enviar: depois de salvar, ele não aparece de novo.

3. Copie a URL

   Abra a conexão: a tela mostra a URL do webhook, no formato https://t.traceclose.com/webhooks/leads/site/<id-da-conexão>, e exemplos prontos para copiar.

4. Monte o envio na sua ferramenta

   Quando a plataforma avisar uma venda aprovada, faça um POST para a URL com o JSON da venda (exemplo abaixo) e o cabeçalho Authorization: Bearer <segredo>.

5. Teste com uma venda

   Mande uma venda de teste com o seu e-mail e confira o lead e a venda no painel.

O JSON da venda

POST https://t.traceclose.com/webhooks/leads/site/<id-da-conexão>
Content-Type: application/json
Authorization: Bearer <segredo>

{
  "version": 1,
  "event": "sale",
  "data": {
    "externalId": "pedido-5001",
    "email": "maria@exemplo.com",
    "phone": "+5511999998888",
    "amountMinor": 49700,
    "currency": "BRL",
    "occurredAt": "2026-10-12T10:15:00-03:00"
  }
}

• externalId: o id do pedido na plataforma. Mandar o mesmo pedido de novo não duplica a venda.
• email ou phone: pelo menos um, para achar o lead. Telefone com DDI (+55…) ou no formato do país da operação.
• amountMinor: o valor em centavos (na menor unidade da moeda), sem vírgula nem ponto: R$ 497,00 vai como 49700.
• currency: a moeda do pedido (BRL, USD…).
• Opcionais: occurredAt (quando foi pago, com fuso), leadExternalId (se você já mandou o lead antes) e eventId (o id do Purchase do pixel, para a Meta não contar duas vezes).

Reembolso

Para cancelar uma venda, mande o evento refund com o mesmo externalId do pedido. Reembolso repetido não dá erro.

{
  "version": 1,
  "event": "refund",
  "data": { "externalId": "pedido-5001" }
}

Origem do comprador (opcional)

Se a plataforma guarda as UTMs ou o fbclid, mande antes o evento lead com o campo attribution (utmSource, utmCampaign, utmContent, fbclid, fbc, fbp…). O formato completo está em leads do formulário do site.

Zapier, Make e n8n

• Zapier: gatilho da sua plataforma (“nova venda”) e ação Webhooks by Zapier, evento POST (ou Custom Request), com o corpo em JSON e o cabeçalho Authorization.
• Make: módulo da sua plataforma e o módulo HTTP › Make a request, método POST, corpo JSON e o cabeçalho.
• n8n: nó da sua plataforma (ou Webhook) e o nó HTTP Request, método POST, corpo JSON e o cabeçalho.
• Se a plataforma manda o valor com casas decimais (497.00), use um passo de fórmula da ferramenta para multiplicar por 100 e arredondar antes de enviar.

Respostas do webhook

• 200: recebido (e também quando é repetido).
• 401: segredo errado, conexão desativada ou URL de outra conexão.
• 400: corpo fora do formato; a resposta indica o campo.
• Erro 5xx ou de rede: envie de novo. A mesma venda não entra duas vezes.

Se o pixel da Meta já está instalado no checkout da plataforma e envia o Purchase, escolha quem envia a compra: desligue o envio do Purchase nesta conexão com um clique (ou desligue o Purchase no pixel do checkout). Assim a Meta recebe a venda uma vez só, e ela continua entrando no painel e no ROAS.

Não funcionou? Veja…

• 400 em toda venda: quase sempre o valor foi com vírgula ou ponto, ou faltou o e-mail e o telefone.
• Perdeu o segredo: gere outro em Editar e troque na ferramenta.
• Venda sem origem no relatório: a plataforma não mandou UTMs; veja parâmetros de URL nos anúncios.

Perguntas frequentes