Webhooks

What is a webhook (callback)

A webhook (also called a callback) is a POST request that PayZu sends to your server when something happens. Unlike the normal API (where you call PayZu), here it's the opposite: PayZu calls you.

Think about a Pix charge. You created it, displayed the QR to the customer, and now you need to know when the customer pays. Two options:

1. Polling, asking every X seconds "did they pay yet? did they pay yet?" (costly, slow, unnecessary).
2. Webhook, letting PayZu notify you as soon as the payment comes in (instant, efficient, recommended).

How to configure

You can receive notifications in two ways:

• Registered webhook (recommended): register a persistent URL at POST /user/webhooks, with HMAC secret and event selection. The same URL applies to all transactions.
• Per-transaction callbackUrl: provide the URL in the callbackUrl field of the body on each created transaction:

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

PayZu will send the callback to this URL every time that transaction changes status (PENDING → COMPLETED, COMPLETED → REFUNDED, etc).

Events

The events field of POST /user/webhooks defines which changes trigger the notification. Leave it empty to receive all.

Seven events track the transaction's status, one for each value:

Three events don't mirror the status:

Retry system

PayZu webhooks have a robust retry system that guarantees delivery even under temporary failures. PayZu resends the same callback up to 40 times with exponential backoff and jitter, better distributing the load and avoiding request spikes.

Security

To ensure integrity and security, restrict access to your webhook endpoint. Request the official PayZu Processamento IP from support and only accept callbacks from that origin.

Delivery headers

INFRACTION_CHANGED arrives with the transaction's status unchanged, so X-Callback-Event is what distinguishes the deliveries when you subscribe to more than one event.

HMAC verification

Every signed delivery carries X-Callback-Signature. Which secret signs depends on the destination:

Validate the signature before processing the body:

Node.js example, using crypto.timingSafeEqual to compare signatures in constant time:

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"),
  );
}

Payload fields

Identification

Status and amounts

COMMISSION identifies a commission entry credited to your account and arrives with TRANSACTION_COMPLETED.

Generated charge (deposit)

Payer

Receiver

Pix payment via key

Settlement and refund

Timestamps

Infraction (Pix dispute)

Best practices

• Respond fast: return 2xx in under 5s. Do heavy processing in a queue/worker, not in the handler.
• Idempotency: dedupe by id plus the event, not just by id + status. The same callback may arrive more than once (retry, successive changes), and INFRACTION_CHANGED doesn't change the status. See Callback dedupe.
• Use clientReference: pass an external identifier when creating the transaction. It comes back in the callback and makes it easier to correlate with your order.
• Restrict by IP: only accept callbacks from PayZu's official IP.
• Respond 2xx to end delivery: any response outside the 2xx range, including 4xx, and any timeout enter the same cycle of up to 40 attempts. To stop the resend, respond 2xx and handle the error on your side.
• Mask payerDocument in logs: printing the payload without masking personal data is an LGPD risk.

Test and resend

Test locally

Expose your localhost via ngrok or Cloudflare Tunnel and trigger the payload manually:

curl -X POST https://your-tunnel.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://your-tunnel.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://your-tunnel.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',
    },
)

Resend a real callback

The resend endpoint depends on where the destination URL is configured.

callbackUrl provided in the transaction:

• POST /user/callbacks/resend/{transactionId}, one transaction
• POST /user/callbacks/resend, batch by filter, with mandatory date window

Both only reach transactions with callbackUrl filled in and do not generate delivery for a registered webhook.

Registered webhook:

• POST /user/callbacks/resend/webhook/{webhookId}, requeues the failed deliveries on that webhook

The webhook resend reprocesses one delivery per pair of transaction and event, and considers a failure any response from 300 on and the absence of a response. An event whose status no longer matches the transaction's current one is still discarded on resend.

The response comes in enqueued, with count (total accepted for resend), truncated, and items. The items list stops at 500 entries. When truncated is true, the resend still covers all count, only the response's list was cut.

Inspect the history

PayZu stores all delivery attempts. Useful for investigating failures:

• GET /user/callbacks, paginated list
• GET /user/callbacks/{id}, detail with status code, response body, response time

Next steps