Assinatura dos callbacks
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:
t=1760140800, v1=5f1c2e9a0b7d4c6e8f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f70
v1 = hex(HMAC_SHA256(segredo, "1760140800." + corpo))| Canal | Segredo |
|---|---|
callbackUrl | O da conta, criado em Segredo dos callbacks. Enquanto a conta não cria o segredo, esses avisos saem sem assinatura. |
| Webhook | O de cada webhook, gerado no cadastro ou em rotate-secret. |
A entrega não informa de qual webhook veio, então use uma URL por webhook para saber qual segredo aplicar.
import crypto from 'node:crypto'
import http from 'node:http'
// Uma rota por canal: cada uma valida com o seu segredo.
const SECRETS = {
'/payzu/callback': process.env.PAYZU_CALLBACK_SECRET,
'/payzu/webhook': process.env.PAYZU_WEBHOOK_SECRET,
}
const TOLERANCE_SECONDS = 300
const SIGNATURE = /^t=(\d+),\s*v1=([0-9a-f]{64})$/
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'))
}
http.createServer(async (req, res) => {
const chunks = []
for await (const chunk of req) chunks.push(chunk)
const raw = Buffer.concat(chunks)
if (!isAuthentic(SECRETS[req.url], req.headers['x-callback-signature'], raw)) {
res.writeHead(401).end()
return
}
const notice = JSON.parse(raw)
// Mesmo aviso, mesma chave: retentativa, reenvio ou os dois canais.
const key = notice.infraction
? `${notice.infraction.id}:${notice.infraction.updatedAt}`
: `${notice.id}:${notice.updatedAt}`
try {
// Grave numa tabela com a chave única ou numa fila durável; chave repetida não é erro.
await storeOnce(key, req.headers['x-callback-event'] ?? 'callbackUrl', notice)
} catch {
res.writeHead(500).end()
return
}
res.writeHead(200).end()
}).listen(3000)Calcule o HMAC sobre os bytes recebidos.
A PayZu assina o resultado de JSON.stringify do corpo, os mesmos bytes que envia. Se o seu framework interpretar e reserializar o JSON, espaços e ordem das chaves podem mudar e a assinatura deixa de conferir.
Compare t com o seu relógio e recuse avisos com mais de 5 minutos de diferença. Cada tentativa sai com um t novo, então essa janela não barra retentativas.
Responda depois de gravar
A PayZu espera a resposta por até 5 segundos e, sem 2xx, tenta de novo. Grave o aviso numa tabela ou numa fila durável, responda 2xx e processe depois. Se a gravação falhar, responda com erro para o aviso voltar na próxima tentativa.
O mesmo aviso pode chegar mais de uma vez.
Isso acontece por retentativa, reenvio ou pelos dois canais, inclusive dentro da janela de 5 minutos. Deduplique os avisos de transação por id + updatedAt e os de INFRACTION_CHANGED só por infraction.id + infraction.updatedAt. Veja Webhooks e callbacks.