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).

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é 72 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.

Verificação HMAC

Cada webhook é assinado com o seu webhook secret, definido ao cadastrar o webhook em POST /user/webhooks. Sua aplicação deve validar a assinatura antes de processar o payload:

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

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

function verifyWebhookSignature(request, webhookSecret) {
  const timestamp = request.headers["x-webhook-timestamp"];
  const nonce = request.headers["x-webhook-nonce"];
  const signature = request.headers["x-webhook-signature"];

  if (typeof signature !== "string" || !/^[0-9a-f]{64}$/i.test(signature)) {
    return false;
  }

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

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

Campos do payload

Identificação

Status e valores

Cobrança gerada (depósito)

Pagador

Recebedor

Saque via chave Pix

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: armazene id + status para deduplicar. O mesmo callback pode chegar mais de uma vez (retentativa, mudanças sucessivas).
• 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.
• Não responda 4xx por erro de validação interna: a PayZu não retenta e o callback se perde.
• 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": "PAYZU20251123104518DF75D20A8F",
    "type": "DEPOSIT",
    "status": "COMPLETED",
    "amount": 99.90,
    "clientReference": "order-1234",
    "virtualAccount": "loja-rj-01",
    "paidAt": "2025-11-23T10:46:26.986Z"
  }'

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

import requests

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

Reenviar um callback real

Para reprocessar um callback que falhou no seu lado (depois de ter ajustado o handler), use os endpoints de reenvio:

• POST /user/callbacks/resend/{transactionId}, reenviar callback de uma transação
• POST /user/callbacks/resend, reenvio em lote

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