PayZu OnboardingIntegração
Verificar a assinatura
Confira em cada entrega o HMAC-SHA256 calculado com o segredo do seu tenant antes de processar o corpo.
Leia os cabeçalhos
cabeçalhos de uma entrega
{
"Content-Type": "application/json",
"X-Callback-Id": "7d2f0c4e-9a51-4b8e-a3c6-1f0e5b7d9c22",
"X-Callback-Event": "proposal.waiting_data",
"X-Callback-Attempt": "2",
"X-Callback-Timestamp": "1791901260",
"X-Callback-Signature": "sha256=<64 caracteres hexadecimais>"
}| Cabeçalho | Conteúdo |
|---|---|
X-Callback-Signature | sha256= seguido do HMAC-SHA256 da string assinada, em hexadecimal. |
X-Callback-Timestamp | O instante da tentativa, que entra na string assinada. |
X-Callback-Id | O id do corpo. |
X-Callback-Event | O event do corpo. |
X-Callback-Attempt | O attempt do corpo. |
A string assinada é o valor de X-Callback-Timestamp, um ponto e o corpo cru, byte a byte.
Confira a assinatura
verificar-callback.js
import { createHmac, timingSafeEqual } from 'node:crypto'
const FORMATO = /^sha256=([0-9a-f]{64})$/
const JANELA_SEGUNDOS = 300
function cabecalho(headers, nome) {
for (const [chave, valor] of Object.entries(headers)) {
if (chave.toLowerCase() === nome) return Array.isArray(valor) ? valor[0] : valor
}
}
// corpoCru: Buffer com os bytes recebidos, antes de qualquer JSON.parse
// headers: objeto simples, como req.headers no Node.js
export function assinaturaConfere(corpoCru, headers, segredo, agora = Date.now()) {
const instante = cabecalho(headers, 'x-callback-timestamp')
const recebida = FORMATO.exec(cabecalho(headers, 'x-callback-signature') ?? '')
if (!instante || !/^\d+$/.test(instante) || !recebida) return false
if (Math.abs(agora / 1000 - Number(instante)) > JANELA_SEGUNDOS) return false
const calculada = createHmac('sha256', segredo).update(instante + '.').update(corpoCru).digest()
return timingSafeEqual(calculada, Buffer.from(recebida[1], 'hex'))
}- Cabeçalhos: leia sem diferenciar maiúsculas.
- Formato: recuse, antes de comparar, assinatura fora do formato
sha256=seguido de 64 caracteres hexadecimais e timestamp com algo além de dígitos. - Timestamp: use como chegou. Uma janela de 300 segundos basta para recusar entrega antiga.
A assinatura muda a cada tentativa.
attempt e X-Callback-Timestamp mudam a cada tentativa de uma entrega, e com eles a assinatura. O id continua o mesmo.