PayZu GatewaySegurança

Assinatura dos webhooks


Nesta páginaComo a assinatura é calculadaConfira no seu servidorResponda depois de gravar

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-Signature
X-Webhook-Timestamp: 1794410459433
X-Webhook-Nonce: 3f9a1c7e5b2d4086a1e3c5b7d9f02468
X-Webhook-Signature: 7a1336718952f2491860e7da2b054e42a45a61d55a3c4c4d77b1f7c056174fb7

X-Webhook-Signature = hex(HMAC_SHA256(segredo, "1794410459433.3f9a1c7e5b2d4086a1e3c5b7d9f02468." + corpo))
CabeçalhoO que traz
X-Webhook-TimestampO instante do envio, em milissegundos desde a época Unix.
X-Webhook-NonceUm valor aleatório, novo a cada envio.
X-Webhook-EventO tipo do evento.

Use como segredo o valor de secret inteiro, como veio na resposta.

Confira no seu servidor

receber-aviso.js
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-Timestamp com 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.

RegraValor
Prazo da respostaAté 5 segundos.
Conta como entregueSó um 2xx. Redirecionamento não é seguido.
Novas tentativas sem 2xx1 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.