Webhooks

O que é um webhook (callback)

Um webhook (também chamado de callback) é uma requisição POST que a PayZu envia para o seu servidor quando algo acontece. Ao contrário da API normal (onde você chama a PayZu), aqui é o oposto: a PayZu chama você.

Pensa numa cobrança Pix. Você criou ela, exibiu o QR ao cliente, e agora precisa saber quando o cliente paga. Duas opções:

1. Polling, ficar perguntando a cada X segundos "já pagou? já pagou?" (custoso, lento, desnecessário).
2. Webhook, deixar a PayZu te avisar assim que o pagamento entrar (instantâneo, eficiente, recomendado).

Como configurar

Você pode receber as notificações de duas formas:

• Webhook cadastrado (recomendado): registre uma URL persistente em POST /user/webhooks, com segredo HMAC e seleção de eventos. A mesma URL vale para todas as transações.
• callbackUrl por transação: informe a URL no campo callbackUrl do body a cada transação criada:

{
  "amount": 99.90,
  "callbackUrl": "https://seusite.com.br/webhooks/payzu",
  "clientReference": "pedido-2025-001"
}

A PayZu vai enviar o callback para essa URL toda vez que aquela transação mudar de status (PENDING → COMPLETED, COMPLETED → REFUNDED, etc).

Eventos

O campo events de POST /user/webhooks define quais mudanças disparam a notificação. Deixe vazio para receber todas.

Sete eventos acompanham o status da transação, um para cada valor:

Três eventos não espelham o status:

Sistema de retry

Os webhooks da PayZu têm um sistema robusto de retentativa que garante a entrega mesmo em falhas temporárias. A PayZu reenvia até 40 vezes o mesmo callback com backoff exponencial e jitter, distribuindo melhor a carga e evitando picos de requisições.

Segurança

Para garantir integridade e segurança, restrinja o acesso ao seu endpoint de webhook. Solicite o IP oficial da PayZu Processamento ao suporte e aceite callbacks apenas dessa origem.

Cabeçalhos da entrega

O INFRACTION_CHANGED chega com o status da transação inalterado, então X-Callback-Event é o que distingue as entregas quando você assina mais de um evento.

Verificação HMAC

Toda entrega assinada traz o X-Callback-Signature. Qual segredo assina depende do destino:

Valide a assinatura antes de processar o corpo:

Exemplo em Node.js, usando crypto.timingSafeEqual para comparar as assinaturas em tempo constante:

const crypto = require("node:crypto");

const TOLERANCE_SECONDS = 300;

function verifyCallbackSignature(request, webhookSecret) {
  const header = request.headers["x-callback-signature"];
  if (typeof header !== "string") return false;

  const parts = Object.fromEntries(
    header.split(",").map((part) => part.trim().split("=")),
  );
  const timestamp = Number(parts.t);
  const signature = parts.v1;

  if (!Number.isInteger(timestamp) || !/^[0-9a-f]{64}$/i.test(signature ?? "")) {
    return false;
  }

  const age = Math.abs(Math.floor(Date.now() / 1000) - timestamp);
  if (age > TOLERANCE_SECONDS) return false;

  const expected = crypto
    .createHmac("sha256", webhookSecret)
    .update(`${timestamp}.${request.rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(signature, "hex"),
  );
}

Campos do payload

Identificação

Status e valores

COMMISSION identifica um lançamento de comissão creditado à sua conta e chega com TRANSACTION_COMPLETED.

Cobrança gerada (depósito)

Pagador

Recebedor

Pagamento Pix via chave

Liquidação e estorno

Timestamps

Infração (disputa Pix)

Boas práticas

• Responda rápido: devolva 2xx em menos de 5s. Processe pesado em fila/worker, não no handler.
• Idempotência: deduplique por id mais o evento, e não só por id + status. O mesmo callback pode chegar mais de uma vez (retentativa, mudanças sucessivas), e o INFRACTION_CHANGED não muda o status. Ver Dedupe de callbacks.
• Use clientReference: passe um identificador externo na criação da transação. Volta no callback e facilita correlacionar com seu pedido.
• Restrinja por IP: aceite callbacks apenas do IP oficial da PayZu.
• Responda 2xx para encerrar a entrega: qualquer resposta fora da faixa 2xx, inclusive 4xx, e qualquer timeout entram no mesmo ciclo de até 40 tentativas. Para parar o reenvio, responda 2xx e trate o erro do seu lado.
• Mascare payerDocument nos logs: imprimir o payload sem mascarar dados pessoais é risco LGPD.

Testar e reenviar

Testar localmente

Exponha seu localhost via ngrok ou Cloudflare Tunnel e dispare o payload manualmente:

curl -X POST https://seu-tunel.ngrok.io/webhooks/payzu \
  -H "Content-Type: application/json" \
  -d '{
    "id": "PAYZU20260811K7M2X9QP4T000000",
    "type": "DEPOSIT",
    "status": "COMPLETED",
    "amount": 99.90,
    "clientReference": "order-1234",
    "virtualAccount": "loja-rj-01",
    "paidAt": "2026-08-11T10:46:26.986Z"
  }'

await fetch('https://seu-tunel.ngrok.io/webhooks/payzu', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    id: 'PAYZU20260811K7M2X9QP4T000000',
    type: 'DEPOSIT',
    status: 'COMPLETED',
    amount: 99.90,
    clientReference: 'order-1234',
    virtualAccount: 'loja-rj-01',
    paidAt: '2026-08-11T10:46:26.986Z',
  }),
});

import requests

requests.post(
    'https://seu-tunel.ngrok.io/webhooks/payzu',
    headers={'Content-Type': 'application/json'},
    json={
        'id': 'PAYZU20260811K7M2X9QP4T000000',
        'type': 'DEPOSIT',
        'status': 'COMPLETED',
        'amount': 99.90,
        'clientReference': 'order-1234',
        'virtualAccount': 'loja-rj-01',
        'paidAt': '2026-08-11T10:46:26.986Z',
    },
)

Reenviar um callback real

O endpoint de reenvio depende de onde a URL de destino está configurada.

callbackUrl informado na transação:

• POST /user/callbacks/resend/{transactionId}, uma transação
• POST /user/callbacks/resend, lote por filtro, com janela de datas obrigatória

Os dois alcançam apenas transações com callbackUrl preenchido e não geram entrega para webhook cadastrado.

Webhook cadastrado:

• POST /user/callbacks/resend/webhook/{webhookId}, reenfileira as entregas que falharam nesse webhook

O reenvio por webhook reprocessa uma entrega por par de transação e evento, e considera falha a resposta a partir de 300 e a ausência de resposta. Evento cujo status já não corresponde ao atual da transação continua sendo descartado no reenvio.

A resposta vem em enqueued, com count (total aceito para reenvio), truncated e items. A lista items para em 500 entradas. Quando truncated é true, o reenvio continua cobrindo todas as count, só a lista da resposta é que foi cortada.

Inspecionar o histórico

A PayZu guarda todas as tentativas de entrega. Útil para investigar falha:

• GET /user/callbacks, lista paginada
• GET /user/callbacks/{id}, detalhe com status code, response body, response time

Próximos passos