Skip to main content

O que você implementa

Um endpoint POST público acessível via HTTPS que recebe notificações assinadas da ClearPago. A plataforma envia um POST com Content-Type: application/json e o header Digital-Signature em cada evento relevante. Você não implementa os webhooks de entrada do parceiro BaaS — esses ficam dentro da plataforma.

Registrar seu endpoint

Antes de receber notificações, registre sua URL:
TODO: confirmar o corpo exato de POST /webhook com a spec interna.

Formato HTTP da notificação

Eventos suportados

Payloads por evento

pix_cash_in

pix_cash_out

pix_cash_in_reversal

event.id em pix_cash_in_reversal é o UUID do cash-in original, não do refund-in. O event.external_id é o externalId do refund-in. Para idempotência, use transaction_id + end_to_end_id do estorno.

pix_cash_out_reversal

Resposta esperada

  • Tempo: responda 2xx em menos de 5 segundos.
  • Código: 200 ou 204.
  • Corpo: pode ser vazio.
  • Em caso de erro: 5xx gera retentativa com backoff; 4xx pode não gerar retentativa.

Segurança

  1. Verificar Digital-Signature antes de qualquer lógica.
  2. Rejeitar com 401 se inválida.
  3. Usar HTTPS com certificado público válido.
  4. Nunca processar payload sem assinatura verificada.

Retry e backoff

A plataforma realiza retentativas em caso de 5xx ou timeout usando backoff exponencial. Por isso:
  • Handlers devem ser idempotentes.
  • Responda 2xx assim que a assinatura for verificada; não aguarde o processamento completo.

Canais de entrega

Não assuma ordem garantida entre eventos. Deduplicação é sempre necessária.

Referências