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çalhoConteúdo
X-Callback-Signaturesha256= seguido do HMAC-SHA256 da string assinada, em hexadecimal.
X-Callback-TimestampO instante da tentativa, que entra na string assinada.
X-Callback-IdO id do corpo.
X-Callback-EventO event do corpo.
X-Callback-AttemptO 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.