GG CheckoutCentro de Ayuda
Ferramentas avançadasAPI de pagamentos

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

Formulário Criar Webhook com os campos Nome da integração, URL da integração e Secret, a Origem em API, o campo Ordens de cobrança e os eventos da cobrança Pix
  1. Em Ferramentas > Webhook, abra a aba Criar Webhook e clique em Adicionar integração.
  2. 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.
  3. Preencha Secret (opcional). No webhook de origem API, o segredo é obrigatório: ele assina as entregas.
  4. Em Origem, escolha API.
  5. Em Ordens de cobrança, escolha as ordens cujas cobranças o webhook recebe. Sem seleção, ele recebe de todas.
  6. Marque os eventos e clique em Criar.

Eventos

Na telaEventoQuando é enviado
PIX geradopayment_intent.requires_actionO Pix foi gerado.
PIX pagopayment_intent.succeededO Pix foi pago.
Falha ao gerar o PIXpayment_intent.failedNenhum gateway da ordem conseguiu gerar o Pix.
PIX vencidopayment_intent.expiredO QR Code venceu sem pagamento, ou a cobrança ficou 2 horas sem uso.
Cobrança canceladapayment_intent.canceledA cobrança foi cancelada.
Pago depois de cancelar ou vencerpayment_intent.succeeded_after_cancelUm 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:

HeaderConteúdo
X-GG-TimestampO momento do envio, em segundos desde 1970.
X-GG-Signaturesha256= 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

En esta página