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:
| Campo | Descrição |
|---|---|
| Deposit webhook URL | URL HTTPS pra onde vão os webhooks de depósitos. |
| Withdrawal webhook URL | URL HTTPS pra onde vão os webhooks de saques. |
| Webhook Signature | Opcional. 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.
{
"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:
clientCallbackUrl(do request de criação) — se informada e válida.- URL por tipo (deposit ou withdrawal) configurada no portal.
- 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:
Content-Type: application/json
Accept: application/json
Authorization: Bearer CLIENT_CALLBACK_TOKEN
X-Webhook-Signature: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
X-Webhook-Timestamp: 1755792000Authorization: Bearer CLIENT_CALLBACK_TOKENé um token fixo emitido pela Zypfy para identificar que a requisição vem dela. Não é o seu JWT.X-Webhook-SignatureeX-Webhook-Timestampsó são enviados se você configurou a signature no portal.
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:
assinatura = HMAC_SHA256(chave = sua_signature, mensagem = "{X-Webhook-Timestamp}.{corpo_bruto_do_request}")Pontos que fazem a validação falhar se ignorados:
- Use o corpo bruto (a string exata recebida), nunca o JSON re-serializado. Reordenar chaves ou mudar espaçamento altera o hash.
- Compare em tempo constante (
crypto.timingSafeEqual,hash_equals), não com==. - Rejeite timestamps antigos — recomendamos uma janela de 5 minutos — para barrar replay.
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:
- o destino tem secret próprio, devolvido uma única vez no cadastro — não é a signature da conta;
- a assinatura vai em
X-Webhook-Signatureno formatot=<epoch>,v1=<hmac>(mesmo HMAC-SHA256 de<timestamp>.<corpo cru>, só o empacotamento muda).
Payload: Deposit
{
"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
| Campo | Tipo | Descrição |
|---|---|---|
type | string | Sempre "Deposit" neste webhook. |
external_id | string | Seu identificador (o que você enviou na criação). |
transaction_id | string | ID da transação na Zypfy. |
txid | string? | TXID EMV do QR Code. |
end_to_end | string? | EndToEnd ID do BACEN (disponível em COMPLETED). |
payer_name | string? | Nome do pagador (pode vir preenchido pelo BACEN). |
payer_cpf | string? | CPF/CNPJ do pagador (pode divergir do enviado se fallback foi usado). |
payer_ispb | string? | ISPB da instituição do pagador. |
status | string | PENDING, PROCESSING, COMPLETED ou FAILED. |
currency | string | Moeda da transação: "BRL" ou "MXN". Depósitos do México chegam neste mesmo endereço — roteie por este campo. Veja Depósitos MXN. |
amount | number | Valor 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_expected | number? | Apenas em MXN/SPEI. Valor que você cobrou. Igual a amount num pagamento integral. |
amount_paid | number? | 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. |
partial | boolean? | Apenas em MXN/SPEI. true quando a cobrança liquidou com pagamento parcial. Veja Depósitos MXN. |
fee | number | Taxa, cobrada sobre o valor que entrou (amount). |
payment_method | string | Meio de pagamento: pix, boleto, card ou spei (México). Use este campo para saber qual fluxo tratar. |
updated_at | string (ISO 8601) | Quando o status mudou. |
error_code | string? | Apenas em FAILED. |
error_message | string? | Apenas em FAILED. |
Exemplo de payload FAILED
{
"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
{
"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
| Campo | Tipo | Descrição |
|---|---|---|
type | string | Sempre "Withdrawal". |
transaction_id | string | ID na Zypfy. Use para mapear no seu banco. |
status | string | PENDING, QUEUE, PROCESSING, COMPLETED, FAILED, REFUNDED, PARTIALLY_REFUNDED. |
amount | number | Valor enviado. |
total | number | amount + fee — valor debitado. |
fee | number | Taxa. |
end_to_end_id | string? | EndToEnd ID (disponível em COMPLETED). |
receiver_name | string? | Nome do destinatário (do DICT/SPI). |
receiver_cpf | string? | CPF/CNPJ do destinatário. |
receiver_ispb | string? | ISPB da instituição do destinatário. |
error_code | string? | Apenas em FAILED. |
error_message | string? | 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
Timeout: A Zypfy espera até 8 segundos pela sua resposta.
Confirmação: Qualquer status
2xx(200, 204, etc.) é considerado sucesso. O corpo da sua resposta é ignorado.Retry automático: a Zypfy reenvia até 3 vezes quando o seu endpoint não responder
2xx:Tentativa Quando 1ª Imediata, no momento em que o status muda 2ª 10 minutos depois, se a 1ª falhou 3ª 30 minutos depois, se a 2ª falhou Após a 3ª falha consecutiva, a Zypfy para de reenviar — você precisa reconciliar por consulta (ver abaixo).
O que conta como falha: resposta fora da faixa
2xx(4xx/5xx), timeout (>8s), ou conexão recusada/DNS/TLS inválido.Idempotência obrigatória: todas as tentativas enviam o mesmo payload com o mesmo
transaction_ideexternal_id. Trate como idempotente (ver "Handler idempotente" abaixo) — não retorne4xx/5xxde propósito quando já tiver processado o evento, isso só dispara reenvios desnecessários.Cobertura: o retry é central no gateway Zypfy e cobre todas as adquirentes (HeartPay, HeartPay 2, Zendry, Zendry 2, MediusPag e demais).
Métricas de entrega são gravadas no banco (
client_callback_attempts,client_callback_status_code,client_callback_error,client_callback_duration_ms,client_callback_next_attempt_at).
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/*:
// 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:
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
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
function validarSignature(string $esperado, ?string $recebido): bool {
if (!$esperado || !$recebido) return false;
return hash_equals($esperado, $recebido);
}# 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
- Endpoint HTTPS (não HTTP) com certificado válido.
-
X-Webhook-Signatureconfigurada no portal e validada no handler. - Handler responde
2xxem < 8s. - Handler é idempotente (dedup por
transaction_id + status). - Rotina de reconciliação rodando a cada 5 min (polling via
/api/transactions/*). - Logs e alertas para erros de handler (ex.: exceção → 5xx → Zypfy não reentrega).
- IP da Zypfy liberado no seu firewall (se você faz allowlist de IPs no ingress).