Repository navigation
v2.3.0 — verificação de assinatura de webhook, prazos e credencial fora de dump
Cadastrar o webhook era metade do caminho. Esta versão entrega a outra: provar que a notificação veio do gateway. Junto vem a auditoria de segurança do bloco 1 — prazo em toda requisição, credencial fora de dump e unidade monetária validada.
Tudo aditivo: nenhuma assinatura de método mudou.
Antes de atualizar
ext-opensslpassou a ser requisito de runtime, por causa da verificação RSA da Woovi. Habilite a extensão antes de atualizar.- Valor decimal na Efí, no PagBank e no Pagar.me agora lança
ValidationExceptionem vez de emitir uma cobrança com o valor errado. Se você mandava10.50onde o gateway espera1050, a cobrança saía de onze centavos sem erro nenhum — agora para na validação, com a conversão na mensagem.
Verificação de assinatura de webhook
Capacidade nova, Capability::WEBHOOK_SIGNATURE, pelo mesmo caminho das outras:
$ok = $gateway->webhookSignature()
->setSecret($segredoDoWebhook)
->setPayload(file_get_contents('php://input'))
->setHeaders(getallheaders())
->verify();| Gateway | O que é verificado | O que isso prova |
|---|---|---|
| Asaas | token no header asaas-access-token |
que o remetente conhece o token — o corpo não é assinado |
| PagBank | x-authenticity-token: SHA-256 de {token}-{corpo cru} |
que o corpo chegou inteiro |
| Mercado Pago | x-signature: HMAC-SHA256 de id:…;request-id:…;ts:…; |
que é da sua aplicação e aponta para aquele recurso |
| Woovi/OpenPix | x-webhook-signature: RSA-SHA256 do corpo, contra as chaves publicadas |
que o corpo veio da Woovi |
| AbacatePay | webhookSecret na query, mais o HMAC do corpo quando a chave é dada |
que a URL é a sua e, com a chave, que o corpo não mudou |
O corpo verificado é sempre o cru (php://input, ou $request->getContent() no Laravel): reserializar o JSON muda o hash. verify() devolve bool, porque assinatura que não bate é resposta — o que levanta ValidationException é uso errado (segredo ausente, corpo vazio, header que não chegou).
Efí, Cielo, Rede e Pagar.me não declaram a capacidade, e isso é de propósito: a Efí notifica por mTLS, Cielo e Rede não mandam assinatura nenhuma e a v5 da Pagar.me não documenta esquema. Nos quatro, webhookSignature() levanta NotImplementedException. Um verificador sem nada para checar teria que responder true, o que é pior que não ter verificação, porque parece ter.
Segurança e robustez
- Prazo em toda requisição: 60s no total, 10s para conectar, pela
PHPay\Http\ClientFactory, que passa a ser o único lugar onde um client nasce. O padrão do Guzzle é esperar para sempre, e um gateway travado prendia o worker até o processo morrer. - Credencial fora de dump:
PHPay\Http\MasksCredentialsdá__debugInfo()a todo gateway e, peloHasHttpClient, a todo recurso — a credencial vira********e oClientinteiro fica oculto, porque ele carrega o token nos headers. Odd()do Symfony VarDumper lê propriedade privada por conta própria e não é coberto. #[\SensitiveParameter]em todo parâmetro que recebe credencial, para não aparecer em stack trace.MoneyrecusaNAN,INFe valor que estouraria os centavos num inteiro de 64 bits. Os três convertiam para0ou davam a volta e viravam negativo, passando por todas as checagens.
Também
CHANGELOG.mdretroativo, cobrindo as cinco releases anteriores.- 440 testes (de 393), nenhum tocando a rede. PHPStan nível 9.
O detalhamento item por item está no CHANGELOG.
Instalação: composer require phpay-io/phpay