Carregando seu workspace…
→Voltar ao dashboard
Webhook universal
Documentação
Integração, rastreamento e configuração
Integração para gateways
Envie pedidos do seu gateway para o GhostScale e veja as vendas atribuídas às campanhas do Meta Ads.
Visão geral
Ao enviar pedidos para o webhook abaixo, cada pagamento vira um evento na Meta com event_id para deduplicação: aprovado → Purchase, além de pendentes, reembolsos, cancelamentos e chargebacks, tudo no painel do cliente.
httpGhostScale
POST {BASE_URL}/api/webhooks/gateway
Authorization: Bearer tb_live_<seu-token>
Content-Type: application/jsonO webhook aceita formatos livres — os campos são detectados por heurística. O
{BASE_URL} é o domínio da GhostScale do cliente, fornecido no painel.Onde o cliente obtém a credencial
No painel, em Integrações → aba Gateways, o cliente cria uma credencial por gateway e recebe o token tb_live_... — exibido uma única vez.
| Valor | Exemplo | Uso |
|---|---|---|
URL do webhook | {BASE_URL}/api/webhooks/gateway | Endpoint para enviar os pedidos |
Token | tb_live_<64 hex> | Enviado como Authorization Bearer |
Authorization header | Bearer tb_live_<64 hex> | Completo, pronto para colar |
No seu painel, ofereça ao cliente dois campos: URL do webhook e Chave de API.
Autenticação
O token é aceito em três posições equivalentes:
httpGhostScale
# Opção 1 — header Authorization (recomendado)
Authorization: Bearer tb_live_<64 hex>
# Opção 2 — header X-TrackBase-Key
X-TrackBase-Key: tb_live_<64 hex>
# Opção 3 — query string
POST {BASE_URL}/api/webhooks/gateway?token=tb_live_<64 hex>Sem token, token inválido ou desativado, a resposta é 401. O token fica na GhostScale apenas como hash SHA-256.
Payload aceito (JSON livre)
Os valores são procurados nos caminhos abaixo, na ordem indicada. Campos ausentes têm padrões seguros.
Identificação
| Campo | Caminhos aceitos (primeiro encontrado vence) |
|---|---|
ID do pedido | idtransaction_idtransactionIdsale_idsaleIddata.iddata.transaction.idorder.id |
ID do evento | event_ideventIdtracking.event_idmetadata.event_iddata.event_id |
Status e valores
| Campo | Caminhos aceitos | Padrão |
|---|---|---|
Status | statuseventtypedata.statusdata.transaction.statusorder.status | pending |
Valor | amountvaluetotalpricedata.amountdata.valuedata.transaction.amountorder.total | 0 |
Moeda | currencydata.currencydata.transaction.currency | BRL |
Regra de centavos: se o valor for inteiro e maior que 10000, ele é dividido por 100 —
12990 vira R$ 129,90. Valores decimais (ex.: 129.90) entram direto.Rastreamento (atribuição da campanha)
Repasse o que vier do navegador do cliente em tracking, metadata ou data:
| Campo | Caminhos aceitos |
|---|---|
fbclid | fbclidtracking.fbclidmetadata.fbclid |
fbc | fbctracking.fbcmetadata.fbc |
fbp | fbptracking.fbpmetadata.fbp |
utm_source | utm_sourcetracking.utm_sourcemetadata.utm_source |
utm_campaign | utm_campaigntracking.utm_campaignmetadata.utm_campaign |
utm_medium | utm_mediumtracking.utm_mediummetadata.utm_medium |
utm_content | utm_contenttracking.utm_contentmetadata.utm_content |
utm_term | utm_termtracking.utm_termmetadata.utm_term |
Status → evento
| Status do seu gateway | Status GhostScale | Evento na Meta |
|---|---|---|
approvedpaidcompletedsucceededsuccessaprovadopago | approved | Purchase |
qualquer outro / ausente | pending | PaymentPending |
refundrefundedreembolso | refunded | Refund |
chargebackcontestado | chargeback | Chargeback |
cancelcancelledfailedrecusadoexpired | cancelled | PaymentCancelled |
Reenvie o mesmo
id quando o pedido mudar de estado (pending → approved, approved → refunded...): o pedido é atualizado e o novo evento registrado.Exemplos
Simples
jsonGhostScale
{
"id": "8788221",
"status": "approved",
"amount": 129.90,
"currency": "BRL"
}Aninhado (transação)
jsonGhostScale
{
"data": {
"transaction": {
"id": "tran_ABC123",
"status": "paid",
"amount": 4990,
"currency": "BRL"
}
}
}Completo (com rastreamento)
jsonGhostScale
{
"id": "75a1d0d1-9b2f-4c6a-8f0e-1b2c3d4e5f60",
"status": "approved",
"amount": 299.00,
"currency": "BRL",
"customer": { "email": "cliente@example.com" },
"tracking": {
"event_id": "a94a8fe5ccb19ba61c4c0873d391e987",
"utm_source": "facebook",
"utm_medium": "paid",
"utm_campaign": "oferta-inverno|2384729384",
"utm_content": "anuncio-a|2384729385",
"utm_term": "conjunto-b|2384729386",
"fbclid": "IwAR1vx...",
"fbp": "fb.1.1668373967365.1976397361"
}
}Teste via cURL
bashGhostScale
curl -X POST "{BASE_URL}/api/webhooks/gateway" \
-H "Authorization: Bearer tb_live_<seu-token>" \
-H "Content-Type: application/json" \
-d '{
"id": "pedido-9999",
"status": "approved",
"amount": 129.90,
"currency": "BRL",
"tracking": {
"utm_source": "facebook",
"utm_campaign": "campanha-x|2384729384",
"fbclid": "IwAR1...",
"fbp": "fb.1.1668373967365.1976397361"
}
}'Respostas e códigos HTTP
| Código | Significado | Corpo |
|---|---|---|
| 200 | Evento registrado (pedido inserido ou atualizado) | { "received": true, "orderId", "status", "event" } |
| 400 | JSON inválido | { "error": "JSON inválido" } |
| 401 | Token ausente / inválido / desativado | { "error": "Credencial ausente" } / "Credencial inválida" |
CORS aberto a qualquer origem; preflight
OPTIONS suportado.Idempotência e reenvios
| Cenário | Comportamento |
|---|---|
| Mesmo id com mesmo status reenviado | Pedido atualizado; evento duplicado ignorado |
| Mesmo id com status novo (ex.: pending → approved) | Pedido atualizado e novo evento registrado |
| Retry da sua fila após falha | Seguro — sem duplicação |
Reenvios em caso de falha de rede ou 5xx são seguros: a operação é idempotente.