PayZu CâmbioSegurança

Assinatura dos webhooks


Confira a assinatura de cada aviso para ter certeza de que ele veio da PayZu e de que o corpo não foi alterado no caminho.

Como a assinatura é calculada

O valor v1 é um HMAC-SHA256, em hexadecimal, calculado sobre o timestamp t (Unix, em segundos), um ponto e o corpo enviado, com o segredo do webhook como chave:

PayZu-Signature
t=1762776001,v1=5f1c2e9a0b7d4c6e8f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f70

v1 = hex(HMAC_SHA256(segredo, "1762776001." + corpo))

Cada webhook tem o seu segredo, mostrado no cadastro e na troca do segredo.

conferir-assinatura.js
import crypto from 'node:crypto'

const TOLERANCE_SECONDS = 300
const SIGNATURE = /^t=(\d+),v1=([0-9a-f]{64})$/

export function isAuthentic(secret, header, raw) {
  const match = SIGNATURE.exec(header ?? '')
  if (!secret || !match) return false
  const [, t, v1] = match
  if (Math.abs(Date.now() / 1000 - Number(t)) > TOLERANCE_SECONDS) return false
  const mac = crypto.createHmac('sha256', secret).update(`${t}.`).update(raw).digest()
  return crypto.timingSafeEqual(mac, Buffer.from(v1, 'hex'))
}

Calcule o HMAC sobre os bytes recebidos.

Se o seu framework interpretar e reserializar o JSON, espaços e ordem das chaves podem mudar e a assinatura deixa de conferir.

Recuse avisos com mais de 300 segundos de diferença.

Compare t com o seu relógio antes de processar.