Estrutura do payload
O payload do webhook é o JSON enviado por POST a cada evento: o evento, o comprador, o pagamento, os produtos, o webhook e as UTMs da visita.
O payload é o conteúdo que o ggCheckout envia à URL do webhook a cada evento. Ele chega em uma requisição POST com Content-Type: application/json e traz o nome do evento, os dados do comprador, do pagamento e dos produtos, a identificação do webhook e os parâmetros UTM da visita. Esta página descreve o payload dos webhooks de origem Checkout.
Headers
Quando o webhook tem um Secret, o ggCheckout envia o valor dele em dois headers, Authorization: Bearer <secret> e x-secret: <secret>. O seu sistema compara esse valor com o segredo cadastrado para confirmar a origem do aviso.
Exemplo de payload
Exemplo de um evento pix.paid, com dados fictícios:
{
"event": "pix.paid",
"createdAt": "2026-11-09T10:30:00Z",
"customer": {
"name": "Cliente Exemplo",
"email": "cliente@example.com",
"document": "00000000000",
"phone": "5511900000000",
"ip": "203.0.113.10"
},
"payment": {
"id": "00000000-0000-0000-0000-000000000000",
"method": "pix.paid",
"paymentMethod": "pix",
"gateway": "nome-do-gateway",
"status": "paid",
"amount": 97.00,
"pixCode": "00020126580014BR.GOV.BCB.PIX..."
},
"product": {
"id": "id-do-produto",
"type": "main",
"title": "Curso Exemplo"
},
"products": [
{ "id": "id-do-produto", "type": "main", "title": "Curso Exemplo" },
{ "id": "id-do-bump", "type": "orderbump", "title": "Ebook Exemplo" }
],
"webhook": {
"id": "id-do-webhook",
"businessId": "id-da-conta",
"events": ["pix.paid", "pix.generated"]
},
"utm_source": "origem",
"utm_medium": "meio",
"utm_campaign": "campanha",
"utm_content": null,
"utm_term": null,
"customerIp": "203.0.113.10"
}Campos
| Campo | O que traz |
|---|---|
event | O evento que gerou o aviso. Os valores estão na tabela de eventos, abaixo. |
createdAt | Data e hora do evento, no formato ISO 8601. |
customer | O comprador: name, email, document (CPF ou CNPJ), phone e ip. |
payment.id | O identificador do pagamento no ggCheckout. |
payment.method | O evento do pagamento, igual ao event. |
payment.paymentMethod | A forma de pagamento, como pix. |
payment.gateway | O gateway que processou o pagamento. |
payment.status | paid, pending, failed, refunded ou charged_back. |
payment.amount | O valor do pagamento. |
payment.pixCode | O código Pix copia e cola. Vem só nos eventos de Pix. |
product | O produto principal da compra: id, type e title. |
products | A lista de itens da compra, com o principal e os adicionais. |
product.type e products[].type | main (principal), orderbump, upsell ou downsell. |
webhook | O webhook que enviou o aviso: id, businessId (a conta) e events (os eventos escolhidos). |
utm_source, utm_medium, utm_campaign, utm_content, utm_term | Os parâmetros UTM do link pelo qual o comprador chegou. Vêm como null quando a visita não tinha UTM. |
customerIp | O IP do comprador. |
Eventos
| Evento | Quando é enviado |
|---|---|
pix.generated | Pix gerado, aguardando pagamento. |
pix.paid | Pix pago. |
pix.expired | Pix expirado sem pagamento. |
pix.failed | Falha no Pix. |
pix.refunded | Pix reembolsado. |
card.generated | Pagamento com cartão em processamento. |
card.pending | Cartão pendente de análise. |
card.paid | Cartão aprovado. |
card.failed | Cartão recusado. |
card.expired | Cartão expirado sem confirmação. |
card.refunded | Cartão reembolsado. |
card.charged_back | Chargeback no cartão. |
subscription.renewed | Assinatura renovada. |
subscription.past_due | Assinatura com pagamento em atraso. |
subscription.canceled | Assinatura cancelada. |
checkout.abandoned | Checkout abandonado. |
quiz.completed | Quiz concluído. |
quiz.lead_captured | Lead capturado no quiz. |
Os webhooks de origem API usam outros eventos e outro formato de payload, descritos em Webhooks da API.
Aviso de teste
Ao criar o webhook, ou ao salvar com outra URL ou outro Secret, o ggCheckout envia um aviso de teste com o evento pix.generated, o comprador Cliente Teste e os produtos escolhidos no webhook, ou Produto Teste quando nenhum foi escolhido. Esse aviso não corresponde a uma venda.
No painel
Ferramentas > Webhook. O payload de cada entrega fica em Histórico de Webhook > Ver Detalhes, aba Requisição.
Páginas relacionadas
- Webhooks: como criar um webhook e escolher os eventos.
- Status de pagamento: o que significa cada status de pagamento no painel.
Webhooks
O webhook avisa outro sistema a cada evento de venda, com um POST em JSON para a URL cadastrada. Os webhooks valem para todos os checkouts da conta.
Ferramentas avançadas
Os recursos do ggCheckout para quem programa ou automatiza: a API de pagamentos, o servidor MCP, o uso de IA e a limpeza de cache.