Webhooks

O Paygrid notifica seu servidor quando um pagamento muda de status — sem você precisar consultar a cada segundo.

1. Crie um endpoint

curl -X POST https://api.paygrid.io/v1/webhooks/endpoints \
  -H "X-Api-Key: sk_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://sua-loja.com/webhooks/paygrid",
    "events": ["payment.approved", "payment.declined", "payment.refunded"]
  }'

A resposta traz o secret (whsec_…) uma única vez. Guarde-o: é usado para verificar a assinatura de cada evento recebido.

2. Formato do evento

{
  "id": "evt_01HZX...",
  "type": "payment.approved",
  "apiVersion": "1",
  "eventVersion": "3",
  "createdAt": "2026-08-23T14:22:11.482Z",
  "data": {
    "paymentId": "pay_01HZX...",
    "transactionId": "tx_01HZX...",
    "reference": "pedido-4472",
    "status": "approved",
    "amount": "1990",
    "currency": "BRL",
    "method": "pix",
    "provider": "pagarme"
  }
}

3. Tipos de evento

Evento	Quando
`payment.approved`	Pagamento aprovado.
`payment.declined`	Pagamento recusado.
`payment.refunded`	Pagamento estornado.
`payment.pending`	Cobrança criada, aguardando confirmação.
`payment.cancelled`	Cobrança cancelada.

4. Verifique a assinatura

Cada evento chega com cabeçalho de assinatura HMAC-SHA256 usando o secret. Nunca confie no evento sem verificar — um evento forjado com URL/segredo de terceiro pode fingir uma aprovação.

Exemplos prontos de verificador em Go e JavaScript estão em examples/verify/ no repositório da API.

5. Entrega e retentativa

Entrega assíncrona (não bloqueia a resposta da cobrança).
Retentativas com backoff quando seu endpoint falha ou demora.
Após várias tentativas, o evento vai para uma fila de dead-letter.
Histórico e reenvio: GET /v1/webhooks/events e POST /v1/webhooks/events/{id}/redeliver.

6. Webhooks inbound (do provedor)

Quando o provedor (ex. Pagar.me) confirma um pagamento, ele chama o Paygrid via POST /v1/providers/{hash}/webhook. Você não precisa se preocupar com isso — o Paygrid consome, projeta o status e dispara seu webhook de saída.