PayZu Conta HubWebhooks e callbacks

Verificar a assinatura


Nesta páginaCabeçalhosEscolha o segredoCalcule o HMAC

Confirme a assinatura de cada aviso antes de processar o data.

Cabeçalhos

Toda entrega traz quatro cabeçalhos.

CabeçalhoPara que serve
X-Payzu-EventRotear sem abrir o corpo. Repete o campo event.
X-Payzu-DeliveryIdentificar a entrega. Repete o id do envelope e não muda entre tentativas.
X-Payzu-TimestampInstante da tentativa atual, em milissegundos Unix. Muda a cada tentativa e entra na assinatura.
X-Payzu-Signaturesha256= mais o HMAC-SHA256, em hexadecimal, de <X-Payzu-Timestamp>.<corpo cru>.

Escolha o segredo

Onde o aviso chegouChave do HMAC
Webhook cadastradoO secret do webhook.
callbackUrlO segredo dos callbacks da conta.

Se um mesmo endereço recebe pelos dois caminhos, teste os dois segredos ou separe os caminhos da URL.

Calcule o HMAC

  • Calcule sobre os bytes do corpo como chegaram, antes do JSON.parse.
  • Compare em tempo constante.
  • Recuse um X-Payzu-Timestamp mais velho do que a tolerância que você definir, para que um aviso capturado não seja reapresentado depois.
verificar-aviso.js
import { createHmac, timingSafeEqual } from 'node:crypto'

// corpoCru: Buffer com o corpo exatamente como chegou
// toleranciaMs: idade máxima aceita para o aviso, definida pela sua política
export function avisoValido(corpoCru, headers, segredo, toleranciaMs) {
  const timestamp = headers['x-payzu-timestamp'] ?? ''
  const instante = Number(timestamp)
  if (!timestamp || !Number.isFinite(instante)) return false
  if (Math.abs(Date.now() - instante) > toleranciaMs) return false

  const base = Buffer.concat([Buffer.from(`${timestamp}.`), corpoCru])
  const esperada = Buffer.from('sha256=' + createHmac('sha256', segredo).update(base).digest('hex'))
  const recebida = Buffer.from(headers['x-payzu-signature'] ?? '')
  return esperada.length === recebida.length && timingSafeEqual(esperada, recebida)
}

A tolerância de tempo não barra as retentativas.

Cada tentativa traz um X-Payzu-Timestamp novo.