Webhooks da API
O webhook de origem API avisa o seu sistema quando a cobrança Pix é gerada, paga, vence, falha ou é cancelada. Cada entrega vem assinada com HMAC.
O webhook da API de pagamentos é o aviso que o ggCheckout envia ao seu sistema, por uma requisição HTTP, quando uma cobrança criada pela API muda de estado. Ele é um webhook de origem API, separado dos webhooks de venda do checkout. Cada entrega traz a cobrança inteira e uma assinatura HMAC, calculada com o segredo do webhook.
Criar o webhook
- Em Ferramentas > Webhook, abra a aba Criar Webhook e clique em Adicionar integração.
- Preencha Nome da integração, com no mínimo 3 caracteres, e URL da integração, o endereço do seu sistema que recebe os avisos.
- Preencha Secret (opcional). No webhook de origem API, o segredo é obrigatório: ele assina as entregas.
- Em Origem, escolha API.
- Em Ordens de cobrança, escolha as ordens cujas cobranças o webhook recebe. Sem seleção, ele recebe de todas.
- Marque os eventos e clique em Criar.
Eventos
| Na tela | Evento | Quando é enviado |
|---|---|---|
| PIX gerado | payment_intent.requires_action | O Pix foi gerado. |
| PIX pago | payment_intent.succeeded | O Pix foi pago. |
| Falha ao gerar o PIX | payment_intent.failed | Nenhum gateway da ordem conseguiu gerar o Pix. |
| PIX vencido | payment_intent.expired | O QR Code venceu sem pagamento, ou a cobrança ficou 2 horas sem uso. |
| Cobrança cancelada | payment_intent.canceled | A cobrança foi cancelada. |
| Pago depois de cancelar ou vencer | payment_intent.succeeded_after_cancel | Um Pix foi pago depois do cancelamento ou do vencimento da cobrança. |
Formato da entrega
{
"id": "evt_7Qm2…",
"type": "payment_intent.succeeded",
"livemode": true,
"created_at": "2026-10-19T15:04:12.000Z",
"data": { "id": "pi_3Hk9…", "object": "payment_intent", "status": "succeeded" }
}O campo data traz a cobrança inteira, no mesmo formato de GET /v1/payment_intents/{id}. Os eventos de chaves de teste chegam com livemode: false.
Verificar a assinatura
Toda entrega traz dois headers:
| Header | Conteúdo |
|---|---|
X-GG-Timestamp | O momento do envio, em segundos desde 1970. |
X-GG-Signature | sha256= seguido do HMAC-SHA256, em hexadecimal, de <timestamp>.<corpo>. A chave do HMAC é o segredo do webhook. |
O cálculo usa o corpo cru da requisição, antes da conversão do JSON. O exemplo em JavaScript abaixo confere a assinatura e recusa entregas com mais de 5 minutos:
import crypto from 'node:crypto';
export function assinaturaValida(corpoCru, timestamp, assinatura, segredo) {
const esperado =
'sha256=' +
crypto.createHmac('sha256', segredo).update(`${timestamp}.${corpoCru}`).digest('hex');
const recente = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
return (
recente &&
assinatura.length === esperado.length &&
crypto.timingSafeEqual(Buffer.from(assinatura), Buffer.from(esperado))
);
}Repetição das entregas
O ggCheckout considera entregue o aviso respondido com um código 2xx. Com outra resposta, a entrega é repetida. A mesma entrega pode chegar mais de uma vez, e o id do evento, iniciado por evt_, identifica as repetições.
No painel
Ferramentas > Webhook, aba Criar Webhook, botão Adicionar integração, com a Origem em API.
Páginas relacionadas
- Primeira cobrança Pix: a criação da cobrança que gera os eventos.
- Webhooks: os webhooks de venda do checkout.
- Modo de teste: os cenários que disparam cada evento sem cobrar ninguém.
Primeira cobrança Pix
Os passos da primeira cobrança Pix pela API de pagamentos: chave de teste, ID da ordem de cobrança, criação da cobrança, Pix na tela e aviso de pagamento.
Idempotência
O header Idempotency-Key faz a API de pagamentos devolver a resposta original quando o mesmo pedido de cobrança é repetido, sem criar outra cobrança.