ZypfyDocs Acessar painel
Guia de integração

Webhooks

A Zypfy notifica seu servidor em tempo real via webhook HTTPS quando uma transação muda de status. Este guia explica tudo que você precisa saber para receber, validar e processar webhooks de forma confiável.

Configuração

Duas formas de configurar para onde a Zypfy envia os webhooks:

1. Via portal (padrão)

Em https://app.zypfy.com/webhooks configure:

CampoDescrição
Deposit webhook URLURL HTTPS pra onde vão os webhooks de depósitos.
Withdrawal webhook URLURL HTTPS pra onde vão os webhooks de saques.
Webhook SignatureOpcional. Segredo estático que a Zypfy inclui no header X-Webhook-Signature.

2. Por requisição (override)

Ao criar cada transação, você pode informar clientCallbackUrl no body. Isso sobrescreve a configuração do portal para aquela transação específica.

json
{
  "amount": 100.00,
  "external_id": "order-2026-0001",
  "clientCallbackUrl": "https://minhaloja.com/webhooks/deposit-especial",
  ...
}

Regra de prioridade

A Zypfy escolhe a URL nesta ordem:

  1. clientCallbackUrl (do request de criação) — se informada e válida.
  2. URL por tipo (deposit ou withdrawal) configurada no portal.
  3. Nenhum webhook é enviado — status só fica disponível via consulta (/api/transactions/*).

Formato da requisição que seu servidor vai receber

Método: POST

Headers:

http
Content-Type: application/json
Accept: application/json
Authorization: Bearer CLIENT_CALLBACK_TOKEN
X-Webhook-Signature: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
X-Webhook-Timestamp: 1755792000

Como validar a assinatura

X-Webhook-Signature é um HMAC-SHA256 calculado sobre a string timestamp.corpo_bruto, usando a sua signature como chave, em hexadecimal:

código
assinatura = HMAC_SHA256(chave = sua_signature, mensagem = "{X-Webhook-Timestamp}.{corpo_bruto_do_request}")

Pontos que fazem a validação falhar se ignorados:

javascript
const crypto = require('crypto');

// Importante: o body precisa chegar como texto bruto.
// Express: app.use('/webhooks', express.raw({ type: 'application/json' }))
function webhookValido(req, signature) {
  const ts  = req.get('X-Webhook-Timestamp');
  const sig = req.get('X-Webhook-Signature');
  if (!ts || !sig) return false;

  // Replay protection: 5 minutos.
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(ts)) > 300) return false;

  const raw = req.body.toString('utf8');
  const esperado = crypto
    .createHmac('sha256', signature)
    .update(`${ts}.${raw}`)
    .digest('hex');

  const a = Buffer.from(esperado, 'utf8');
  const b = Buffer.from(sig, 'utf8');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Gere ou consulte a sua signature no portal, em Configurações.

Webhook de cartão virtual

Compra, recusa, carga, estorno e mudança de status de cartão virtual têm um canal próprio: você cadastra os destinos em POST /api/v1/cards/webhooks (ou manda webhookUrl na emissão do cartão) e recebe eventos card.*. Detalhes no guia Cartões virtuais.

Duas diferenças em relação ao webhook de PIX descrito acima:

Payload: Deposit

json
{
  "type": "Deposit",
  "external_id": "order-2026-0001",
  "transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "txid": "TXID123ABC",
  "end_to_end": "E0041696820240617152400000000001",
  "payer_name": "João Silva",
  "payer_cpf": "12345678901",
  "payer_ispb": "12345678",
  "status": "COMPLETED",
  "currency": "BRL",
  "amount": 100.00,
  "fee": 2.50,
  "payment_method": "pix",
  "updated_at": "2026-04-18T12:05:00.000Z"
}

Campos

CampoTipoDescrição
typestringSempre "Deposit" neste webhook.
external_idstringSeu identificador (o que você enviou na criação).
transaction_idstringID da transação na Zypfy.
txidstring?TXID EMV do QR Code.
end_to_endstring?EndToEnd ID do BACEN (disponível em COMPLETED).
payer_namestring?Nome do pagador (pode vir preenchido pelo BACEN).
payer_cpfstring?CPF/CNPJ do pagador (pode divergir do enviado se fallback foi usado).
payer_ispbstring?ISPB da instituição do pagador.
statusstringPENDING, PROCESSING, COMPLETED ou FAILED.
currencystringMoeda da transação: "BRL" ou "MXN". Depósitos do México chegam neste mesmo endereço — roteie por este campo. Veja Depósitos MXN.
amountnumberValor que efetivamente entrou e virou saldo (bruto, antes da taxa). No PIX é sempre o valor cobrado; no SPEI o pagador escolhe quanto manda, então pode ser menor.
amount_expectednumber?Apenas em MXN/SPEI. Valor que você cobrou. Igual a amount num pagamento integral.
amount_paidnumber?Apenas em MXN/SPEI. Total transferido pelo pagador, incluindo excedente — se ele paga a mais, fica maior que amount, porque o crédito é limitado ao valor cobrado.
partialboolean?Apenas em MXN/SPEI. true quando a cobrança liquidou com pagamento parcial. Veja Depósitos MXN.
feenumberTaxa, cobrada sobre o valor que entrou (amount).
payment_methodstringMeio de pagamento: pix, boleto, card ou spei (México). Use este campo para saber qual fluxo tratar.
updated_atstring (ISO 8601)Quando o status mudou.
error_codestring?Apenas em FAILED.
error_messagestring?Apenas em FAILED.

Exemplo de payload FAILED

json
{
  "type": "Deposit",
  "external_id": "order-2026-0009",
  "transaction_id": "c3d4e5f6-...",
  "txid": null,
  "end_to_end": null,
  "payer_name": null,
  "payer_cpf": null,
  "payer_ispb": null,
  "status": "FAILED",
  "amount": 100.00,
  "fee": 0,
  "updated_at": "2026-04-18T12:05:00.000Z",
  "error_code": "PROVIDER_REJECTED",
  "error_message": "Cobrança expirada antes do pagamento."
}

Payload: Withdrawal

json
{
  "type": "Withdrawal",
  "transaction_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "status": "COMPLETED",
  "amount": 50.00,
  "total": 52.50,
  "fee": 2.50,
  "end_to_end_id": "E0041696820240617152400000000002",
  "receiver_name": "João Silva",
  "receiver_cpf": "12345678901",
  "receiver_ispb": "87654321"
}

Campos

CampoTipoDescrição
typestringSempre "Withdrawal".
transaction_idstringID na Zypfy. Use para mapear no seu banco.
statusstringPENDING, QUEUE, PROCESSING, COMPLETED, FAILED, REFUNDED, PARTIALLY_REFUNDED.
amountnumberValor enviado.
totalnumberamount + fee — valor debitado.
feenumberTaxa.
end_to_end_idstring?EndToEnd ID (disponível em COMPLETED).
receiver_namestring?Nome do destinatário (do DICT/SPI).
receiver_cpfstring?CPF/CNPJ do destinatário.
receiver_ispbstring?ISPB da instituição do destinatário.
error_codestring?Apenas em FAILED.
error_messagestring?Apenas em FAILED.

Note que o payload de Withdrawal não inclui external_id. Se você precisa mapear pelo seu ID, guarde transaction_id (que vem na resposta do POST) vinculado ao seu external_id no seu banco.

Entrega e retry

Reconciliação obrigatória (não dependa só do webhook)

Este é o item mais importante deste guia. A entrega de webhooks não é garantida: timeout, network partition, deploy do seu servidor, firewall bloqueando, ou até um bug seu no handler podem fazer a notificação falhar.

Implemente reconciliação periódica via GET /api/transactions/*:

javascript
// A cada 5 minutos, buscar transações PENDING há mais de 10 min e consultar status
async function reconcilePending() {
  const token = await getToken();
  const rows = await db.query(`
    SELECT external_id FROM pedidos
    WHERE status IN ('PENDING','QUEUE')
      AND updated_at < NOW() - INTERVAL '10 minutes'
  `);
  for (const { external_id } of rows) {
    const { data } = await axios.get(
      `https://api.zypfy.com/api/transactions/deposit`,
      {
        headers: { Authorization: `Bearer ${token}` },
        params: { external_id },
      }
    );
    if (data.deposit && data.deposit.status !== 'PENDING') {
      await db.query(`
        UPDATE pedidos SET status=$1, updated_at=NOW()
        WHERE external_id=$2
      `, [data.deposit.status, external_id]);
    }
  }
}
setInterval(reconcilePending, 5 * 60 * 1000);

Handler idempotente

Seu endpoint vai receber webhooks duplicados em alguns cenários (retentativa do seu proxy, testes manuais, replay pelo suporte). O handler deve ser idempotente:

javascript
app.post('/webhooks/deposit', async (req, res) => {
  const { transaction_id, status, external_id } = req.body;

  // 1. Dedup por transaction_id — se já processei esse evento com esse status, ignoro
  const alreadyProcessed = await db.query(
    `SELECT 1 FROM webhook_events WHERE transaction_id=$1 AND status=$2`,
    [transaction_id, status]
  );
  if (alreadyProcessed.rows.length) return res.sendStatus(200);

  // 2. Grava o evento primeiro (fonte da verdade)
  await db.query(`
    INSERT INTO webhook_events (transaction_id, status, payload, received_at)
    VALUES ($1, $2, $3, NOW())
  `, [transaction_id, status, req.body]);

  // 3. Processa lógica de negócio
  if (status === 'COMPLETED') {
    await liberarPedido(external_id);
  } else if (status === 'FAILED') {
    await cancelarPedido(external_id);
  }

  res.sendStatus(200);
});

Validação do X-Webhook-Signature

javascript
import crypto from 'crypto';

function validarSignature(req) {
  const esperado = process.env.ZYPFY_WEBHOOK_SIGNATURE;
  const recebido = req.headers['x-webhook-signature'];
  if (!esperado || !recebido) return false;
  // Comparação em tempo constante previne timing attacks
  const a = Buffer.from(esperado);
  const b = Buffer.from(recebido);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post('/webhooks/deposit', (req, res) => {
  if (!validarSignature(req)) return res.sendStatus(401);
  // ...
});
php
// PHP
function validarSignature(string $esperado, ?string $recebido): bool {
    if (!$esperado || !$recebido) return false;
    return hash_equals($esperado, $recebido);
}
python
# Python
import hmac
def validar_signature(esperado: str, recebido: str | None) -> bool:
    if not esperado or not recebido: return False
    return hmac.compare_digest(esperado, recebido)

Checklist de produção