Skip to content

v2.3.0 — verificação de assinatura de webhook, prazos e credencial fora de dump

Choose a tag to compare

@mariolucasdev mariolucasdev released this 22 Oct 11:43
· 78 commits to develop since this release
1056922

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-openssl passou 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 ValidationException em vez de emitir uma cobrança com o valor errado. Se você mandava 10.50 onde o gateway espera 1050, 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\MasksCredentials dá __debugInfo() a todo gateway e, pelo HasHttpClient, a todo recurso — a credencial vira ******** e o Client inteiro fica oculto, porque ele carrega o token nos headers. O dd() 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.
  • Money recusa NAN, INF e valor que estouraria os centavos num inteiro de 64 bits. Os três convertiam para 0 ou davam a volta e viravam negativo, passando por todas as checagens.

Também

  • CHANGELOG.md retroativo, 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