PayZu PaymentsWebhooks

Validação da assinatura


Confira a assinatura de cada aviso antes de processá-lo e responda 2xx em até 5 segundos para que a PayZu não o envie de novo.

Verifique a assinatura

CabeçalhoPara que serve
X-Webhook-SignatureA assinatura que você confere: HMAC-SHA256 em hexadecimal, calculado com o segredo de assinatura.
X-Webhook-TimestampMilissegundos desde 01/01/1970. Entra na string assinada. Use para recusar avisos fora da sua janela de tempo.
X-Webhook-NonceValor aleatório, diferente em cada envio. Entra na string assinada. Use para recusar uma requisição que chega pela segunda vez.
  • String assinada: <X-Webhook-Timestamp>.<X-Webhook-Nonce>.<corpo>, com o corpo nos bytes em que chegou. Um JSON reserializado muda a assinatura.
  • Janela de tempo: recomendamos recusar avisos com X-Webhook-Timestamp a mais de 5 minutos do seu relógio.
  • Segredo: faz parte da credencial da conta, ao lado do client_id. Nenhuma rota do PayZu Payments o retorna.
verificar-aviso.js
import { createHmac, timingSafeEqual } from 'node:crypto'

const JANELA_MS = 5 * 60 * 1000

// rawBody: Buffer com os bytes do corpo, antes do JSON.parse
// noncesVistos: Map do nonce aceito para o instante em que ele sai da janela
export function avisoValido(rawBody, headers, secret, noncesVistos) {
  const timestamp = headers['x-webhook-timestamp']
  const nonce = headers['x-webhook-nonce']
  const recebida = headers['x-webhook-signature'] ?? ''
  if (!timestamp || !nonce) return false
  const agora = Date.now()
  if (Math.abs(agora - Number(timestamp)) > JANELA_MS) return false
  for (const [visto, vence] of noncesVistos) if (vence < agora) noncesVistos.delete(visto)
  if (noncesVistos.has(nonce)) return false

  const base = Buffer.concat([Buffer.from(`${timestamp}.${nonce}.`), rawBody])
  const esperada = Buffer.from(createHmac('sha256', secret).update(base).digest('hex'))
  const informada = Buffer.from(recebida)
  if (esperada.length !== informada.length || !timingSafeEqual(esperada, informada)) return false

  noncesVistos.set(nonce, Number(timestamp) + JANELA_MS)
  return true
}

O Map do exemplo vale só dentro de um processo.

Com mais de uma instância recebendo avisos, guarde os nonces num cache compartilhado e grave cada um numa operação atômica, depois de conferir a assinatura, com expiração em X-Webhook-Timestamp + 5 minutos, o fim da janela daquele aviso, como SET <nonce> 1 NX PXAT <timestamp + 300000> no Redis. Se a gravação não acontecer, o nonce já foi usado e o aviso deve ser recusado.

Responda ao aviso

Responda 2xx direto, sem redirecionar, assim que gravar o aviso, e faça o processamento fora da requisição. Sem 2xx em 5 segundos, o aviso volta a ser enviado:

Nova tentativaEspera depois da anterior
1ª1 minuto
2ª10 minutos
3ª1 hora
4ª6 horas
5ª24 horas
  • Total: o envio inicial e mais 5 tentativas. Se a quinta tentativa também ficar sem 2xx, o aviso é descartado; recupere o estado das cobranças do período com GET /charges.
  • Cada tentativa: sai com X-Webhook-Timestamp e X-Webhook-Nonce novos, e data mostra a cobrança como ela está no momento da tentativa.

O mesmo evento pode chegar mais de uma vez, e cada entrega traz um nonce novo.

O nonce não serve para reconhecer uma repetição do evento. Identifique a cobrança por data.id e aja pelo estado dela, nunca pela quantidade de avisos.

MeioCampos que mostram o estado
CartãocreditCardPayment.status, reversedDate, reversedAmount e chargebacks. O estorno feito fora da API da PayZu chega com reversedAmount nulo.
PixpixPayment.status e pixPayment.refunds