Skip to main content

O que são os webhooks do comerciante

Os webhooks do comerciante são notificações HTTP enviadas pela ClearPago ao seu endpoint sempre que um evento relevante ocorre em uma transação. São a principal forma de saber que um pagamento foi confirmado, que um envio foi liquidado ou que uma devolução foi processada. Você precisa:
  1. Expor um endpoint POST público via HTTPS.
  2. Registrar a URL na plataforma com os eventos desejados.
  3. Implementar verificação de assinatura e idempotência.

Eventos suportados

Registrar um webhook

TODO: confirmar o formato exato do corpo do POST /webhook com a spec OpenAPI interna — o exemplo acima é baseado nas convenções da plataforma.

Listar webhooks registrados

Use para verificar se a URL correta está cadastrada antes de trocar de ambiente ou domínio.

Remover um webhook

Obtenha o webhook_id da listagem (GET /webhook).

Implementar o endpoint receptor

Estrutura mínima

Seu endpoint deve:
  1. Aceitar POST com Content-Type: application/json.
  2. Ler o corpo bruto (raw body) para validar a assinatura.
  3. Verificar a Digital-Signature antes de qualquer lógica.
  4. Responder 200 (ou 204) em menos de 5 segundos.
  5. Executar a lógica de negócio de forma assíncrona (fila, worker, etc.) se necessário.

Exemplo de handler (Node.js — estrutura)

Raw body é essencial. A assinatura é calculada sobre o corpo antes do parse JSON. Middlewares que modificam o buffer (ex.: express.json() sem salvar o raw) podem invalidar a verificação.

Idempotência no handler

Armazene uma tabela de eventos processados com chave composta: Para pix_cash_in_reversal, use transaction_id + end_to_end_id do estorno (não apenas event.id, que aponta para o cash-in original) para evitar colisão entre devoluções parciais.

Segurança do endpoint

  • Use HTTPS com certificado válido (não autoassinado).
  • Não exponha o endpoint na internet sem autenticação por assinatura.
  • Registre logs de cada requisição recebida com X-Correlation-ID e timestamp.
  • Retorne 401 ou 400 se a assinatura for inválida; nunca processe sem verificar.

Retentativas da plataforma

Se o seu endpoint retornar 5xx ou não responder no tempo esperado, a plataforma realiza retentativas com backoff exponencial. Isso reforça a necessidade de handlers idempotentes.

Referências