PayZu Conta HubWebhooks e callbacks
Verificar a assinatura
Confirme a assinatura de cada aviso antes de processar o data.
Cabeçalhos
Toda entrega traz quatro cabeçalhos.
| Cabeçalho | Para que serve |
|---|---|
X-Payzu-Event | Rotear sem abrir o corpo. Repete o campo event. |
X-Payzu-Delivery | Identificar a entrega. Repete o id do envelope e não muda entre tentativas. |
X-Payzu-Timestamp | Instante da tentativa atual, em milissegundos Unix. Muda a cada tentativa e entra na assinatura. |
X-Payzu-Signature | sha256= mais o HMAC-SHA256, em hexadecimal, de <X-Payzu-Timestamp>.<corpo cru>. |
Escolha o segredo
| Onde o aviso chegou | Chave do HMAC |
|---|---|
| Webhook cadastrado | O secret do webhook. |
callbackUrl | O 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-Timestampmais 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.