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çalho | Para que serve |
|---|---|
X-Webhook-Signature | A assinatura que você confere: HMAC-SHA256 em hexadecimal, calculado com o segredo de assinatura. |
X-Webhook-Timestamp | Milissegundos desde 01/01/1970. Entra na string assinada. Use para recusar avisos fora da sua janela de tempo. |
X-Webhook-Nonce | Valor 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-Timestampa 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.
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 tentativa | Espera 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-TimestampeX-Webhook-Noncenovos, edatamostra 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.
| Meio | Campos que mostram o estado |
|---|---|
| Cartão | creditCardPayment.status, reversedDate, reversedAmount e chargebacks. O estorno feito fora da API da PayZu chega com reversedAmount nulo. |
| Pix | pixPayment.status e pixPayment.refunds |