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:- Expor um endpoint
POSTpúblico via HTTPS. - Registrar a URL na plataforma com os eventos desejados.
- 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
Remover um webhook
webhook_id da listagem (GET /webhook).
Implementar o endpoint receptor
Estrutura mínima
Seu endpoint deve:- Aceitar
POSTcomContent-Type: application/json. - Ler o corpo bruto (raw body) para validar a assinatura.
- Verificar a
Digital-Signatureantes de qualquer lógica. - Responder
200(ou204) em menos de 5 segundos. - 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-IDe timestamp. - Retorne
401ou400se a assinatura for inválida; nunca processe sem verificar.
Retentativas da plataforma
Se o seu endpoint retornar5xx ou não responder no tempo esperado, a plataforma realiza retentativas com backoff exponencial. Isso reforça a necessidade de handlers idempotentes.

