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.
Cada webhook tem o seu segredo, que vem em secret só no cadastro e na troca do segredo.
Como a assinatura é calculada
O valor de X-Webhook-Signature é um HMAC-SHA256, em hexadecimal, calculado com o segredo do webhook sobre o timestamp, um ponto, o nonce, outro ponto e o corpo enviado:
X-Webhook-Timestamp: 1794410459433
X-Webhook-Nonce: 3f9a1c7e5b2d4086a1e3c5b7d9f02468
X-Webhook-Signature: 7a1336718952f2491860e7da2b054e42a45a61d55a3c4c4d77b1f7c056174fb7
X-Webhook-Signature = hex(HMAC_SHA256(segredo, "1794410459433.3f9a1c7e5b2d4086a1e3c5b7d9f02468." + corpo))| Cabeçalho | O que traz |
|---|---|
X-Webhook-Timestamp | O instante do envio, em milissegundos desde a época Unix. |
X-Webhook-Nonce | Um valor aleatório, novo a cada envio. |
X-Webhook-Event | O tipo do evento. |
Use como segredo o valor de secret inteiro, como veio na resposta.
Confira no seu servidor
import crypto from 'node:crypto'
import http from 'node:http'
const SECRET = process.env.PAYZU_WEBHOOK_SECRET
const TOLERANCE_MS = 5 * 60 * 1000
const TIMESTAMP = /^\d+$/
const SIGNATURE = /^[0-9a-f]{64}$/
const MAX_BODY_BYTES = 1024 * 1024
function isAuthentic(headers, raw) {
const timestamp = headers['x-webhook-timestamp'] ?? ''
const nonce = headers['x-webhook-nonce'] ?? ''
const signature = headers['x-webhook-signature'] ?? ''
if (!SECRET || !nonce || !TIMESTAMP.test(timestamp) || !SIGNATURE.test(signature)) return false
if (Math.abs(Date.now() - Number(timestamp)) > TOLERANCE_MS) return false
const mac = crypto.createHmac('sha256', SECRET).update(`${timestamp}.${nonce}.`).update(raw).digest()
return crypto.timingSafeEqual(mac, Buffer.from(signature, 'hex'))
}
// Lê o corpo sem guardar mais que MAX_BODY_BYTES: acima disso, retorna null.
async function readBody(req) {
const chunks = []
let size = 0
for await (const chunk of req) {
size += chunk.length
if (size <= MAX_BODY_BYTES) chunks.push(chunk)
}
return size > MAX_BODY_BYTES ? null : Buffer.concat(chunks)
}
async function handle(req, res) {
const raw = await readBody(req)
if (!raw) {
res.writeHead(413).end()
return
}
const { headers } = req
if (!isAuthentic(headers, raw)) {
res.writeHead(401).end()
return
}
const event = JSON.parse(raw)
const nonceExpiresAt = Number(headers['x-webhook-timestamp']) + TOLERANCE_MS
// Nonce já recebido é o mesmo envio repetido por outra pessoa: recuse.
if (!(await claimNonce(headers['x-webhook-nonce'], nonceExpiresAt))) {
res.writeHead(401).end()
return
}
// Grave numa tabela com o id do evento como chave única ou numa fila durável; id repetido não é erro.
await storeOnce(event.id, event)
res.writeHead(200).end()
}
// Corpo interrompido no meio, falha no cache ou na gravação: 500, sem derrubar o servidor, e o aviso volta na próxima tentativa.
http.createServer((req, res) => {
handle(req, res).catch(() => {
if (!res.headersSent) res.writeHead(500)
res.end()
})
}).listen(3000)claimNonce grava o nonce num cache compartilhado entre as instâncias do seu servidor, numa operação atômica que expira no fim da janela daquele aviso, como SET <nonce> 1 NX PXAT <timestamp + 300000> no Redis, e retorna false quando o nonce já existia.
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.
Recuse o aviso em dois casos:
X-Webhook-Timestampcom mais de 5 minutos de diferença do seu relógio;- nonce já recebido.
Cada tentativa sai com timestamp e nonce novos, então essas regras não barram as novas tentativas. Depois da troca do segredo, toda entrega sai assinada com o segredo novo, inclusive as novas tentativas de eventos anteriores.
Responda depois de gravar
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.
| Regra | Valor |
|---|---|
| Prazo da resposta | Até 5 segundos. |
| Conta como entregue | Só um 2xx. Redirecionamento não é seguido. |
Novas tentativas sem 2xx | 1 minuto, 10 minutos, 1 hora, 6 horas e 24 horas depois da tentativa anterior. |
O mesmo evento pode chegar mais de uma vez.
Isso acontece por nova tentativa ou por reenvio. O id do evento é o mesmo em todas as tentativas: deduplique por ele. Veja Webhooks.