Integração via Webhook (Genérico)

Envie vendas de qualquer checkout pro Trackou com um POST HTTP.

Endpoint

POST https://trackou.io/api/webhooks/sales

A URL é a mesma pra todas as integrações. A chave no header identifica o seu dashboard.

Autenticação

x-webhook-secret: SUA_CHAVE

Envie a chave da integração no header x-webhook-secret. Você obtém a chave ao criar uma integração "Genérico" na página Integrações.

Eventos

O campo event define o status da venda. Só sale.approved dispara o evento Purchase via CAPI.

Evento	Significado
`sale.pending`	Pix/boleto gerado (pagamento pendente)
`sale.approved`	Venda aprovada/paga: dispara Purchase no CAPI
`sale.refunded`	Venda reembolsada
`sale.chargeback`	Chargeback (estorno)

Corpo (JSON)

Apenas transaction_id e amount são obrigatórios. Os demais enriquecem o rastreamento e a atribuição.

{
  "event": "sale.approved",
  "transaction_id": "abc123",
  "amount": 197.00,
  "currency": "BRL",
  "product_name": "Curso XYZ",
  "customer_name": "João Silva",
  "customer_email": "joao@email.com",
  "customer_phone": "11999998888",
  "payment_method": "pix",
  "utm_source": "facebook",
  "utm_campaign": "campanha|23850000000000",
  "fbclid": "AbCdEf",
  "fbc": "fb.1.1700000000.AbCdEf",
  "fbp": "fb.1.1700000000.1234567890",
  "client_ip_address": "203.0.113.42",
  "client_user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X)",
  "event_source_url": "https://checkout.seusite.com/pedido",
  "external_id": "cliente_8842",
  "country": "br",
  "sale_date": "2026-06-28T15:30:00Z"
}

Básicos

Campo	Tipo	Obrigatório	Descrição
`event`	string	Não	Tipo do evento. Default sale.approved.
`transaction_id`	string	Sim	ID único da transação/pedido.
`amount`	number	Sim	Valor da venda.
`currency`	string	Não	Moeda (ISO 4217). Default BRL.

Produto

Campo	Tipo	Obrigatório	Descrição
`product_name`	string	Não	Nome do produto.
`product_id`	string	Não	ID do produto.
`offer_id`	string	Não	ID da oferta.
`offer_name`	string	Não	Nome da oferta.

Cliente

Campo	Tipo	Obrigatório	Descrição
`customer_name`	string	Não	Nome do cliente.
`customer_email`	string	Não	Email do cliente (usado no match do CAPI).
`customer_phone`	string	Não	Telefone do cliente (usado no match do CAPI).

Pagamento

Campo	Tipo	Obrigatório	Descrição
`platform`	string	Não	Plataforma de checkout (ex: vex).
`gateway`	string	Não	Gateway de pagamento (ex: stripe).
`payment_method`	string	Não	pix \| credit_card \| boleto \| debit.
`installments`	number	Não	Número de parcelas.

UTMs e rastreamento

Campo	Tipo	Obrigatório	Descrição
`utm_source`	string	Não	utm_source do anúncio.
`utm_campaign`	string	Não	utm_campaign (pode conter o ID da campanha).
`utm_medium`	string	Não	utm_medium (pode conter o ID do conjunto).
`utm_content`	string	Não	utm_content (pode conter o ID do anúncio).
`utm_term`	string	Não	utm_term.
`fbclid`	string	Não	Click ID do Facebook.
`fbc`	string	Não	Cookie _fbc do clique no anúncio da Meta. Melhora a atribuição do CAPI.
`fbp`	string	Não	Cookie _fbp do navegador do comprador (Meta).
`client_ip_address`	string	Não	IP do comprador no checkout, enviado ao CAPI.
`client_user_agent`	string	Não	User-agent do navegador do comprador, enviado ao CAPI.
`event_source_url`	string	Não	URL da página onde a compra aconteceu.
`external_id`	string	Não	Seu identificador do cliente. Vai hasheado pra Meta.
`country`	string	Não	País do comprador em ISO de duas letras (ex.: BR).
`gclid`	string	Não	Click ID do Google.
`sck`	string	Não	Parâmetro de rastreamento sck.
`src`	string	Não	Origem (src).

IDs do Meta

Campo	Tipo	Obrigatório	Descrição
`meta_campaign_id`	string	Não	ID da campanha Meta (ou extraído do utm_campaign).
`meta_adset_id`	string	Não	ID do conjunto Meta (ou extraído do utm_medium).
`meta_ad_id`	string	Não	ID do anúncio Meta (ou extraído do utm_content).

Outros

Campo	Tipo	Obrigatório	Descrição
`sale_date`	string	Não	Data/hora da venda (ISO 8601).
`metadata`	object	Não	Objeto livre com dados extras que quiser guardar.

Exemplo (cURL)

curl -X POST https://trackou.io/api/webhooks/sales \
  -H "Content-Type: application/json" \
  -H "x-webhook-secret: SUA_CHAVE" \
  -d '{
  "event": "sale.approved",
  "transaction_id": "abc123",
  "amount": 197.00,
  "currency": "BRL",
  "product_name": "Curso XYZ",
  "customer_name": "João Silva",
  "customer_email": "joao@email.com",
  "customer_phone": "11999998888",
  "payment_method": "pix",
  "utm_source": "facebook",
  "utm_campaign": "campanha|23850000000000",
  "fbclid": "AbCdEf",
  "fbc": "fb.1.1700000000.AbCdEf",
  "fbp": "fb.1.1700000000.1234567890",
  "client_ip_address": "203.0.113.42",
  "client_user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X)",
  "event_source_url": "https://checkout.seusite.com/pedido",
  "external_id": "cliente_8842",
  "country": "br",
  "sale_date": "2026-06-28T15:30:00Z"
}'

Resposta

200 OK com o id da venda. Reenvios com o mesmo transaction_id são idempotentes (atualizam a venda em vez de duplicar).

{ "success": true, "action": "created", "sale_id": "..." }