Visão Geral
Os webhooks permitem que você receba notificações em tempo real sobre mudanças no status dos pagamentos PIX. Quando o status de um pagamento muda, nossa API enviará uma requisição POST para a URL configurada.
Configuração
Para receber webhooks, configure a URL no momento da criação do pagamento PIX:
{
"walletAddress": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
"network": "bitcoin",
"amount": 100.00,
"webhookUrl": "https://meusite.com/webhook/pix-payment"
}
Estrutura do Webhook
Assinatura HMAC-SHA256 para validação
Timestamp Unix da requisição
Corpo da Requisição
ID único do pagamento PIX
Endereço da carteira cripto de destino
Quantidade de criptomoeda enviada
Hash da transação cripto (quando status = paid)
Data de confirmação do pagamento (quando status = paid)
Exemplo de Webhook
Pagamento Confirmado
{
"id": "pix_123456789",
"status": "paid",
"walletAddress": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
"network": "bitcoin",
"amount": 100.00,
"cryptoAmount": 0.0004,
"cryptoTransactionHash": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
"paidAt": "2024-01-15T11:15:00Z",
"timestamp": "2024-01-15T11:15:05Z"
}
Pagamento Expirado
{
"id": "pix_123456789",
"status": "expired",
"walletAddress": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
"network": "bitcoin",
"amount": 100.00,
"cryptoAmount": 0.0004,
"cryptoTransactionHash": null,
"paidAt": null,
"timestamp": "2024-01-15T11:30:05Z"
}
Validação da Assinatura
Para garantir a autenticidade do webhook, valide a assinatura HMAC-SHA256:
const crypto = require('crypto');
function validateWebhookSignature(payload, signature, secret) {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature, 'hex'),
Buffer.from(expectedSignature, 'hex')
);
}
// Exemplo de uso
app.post('/webhook/pix-payment', (req, res) => {
const signature = req.headers['x-3x-signature'];
const payload = JSON.stringify(req.body);
if (validateWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
// Processar webhook
console.log('Webhook válido:', req.body);
res.status(200).send('OK');
} else {
res.status(401).send('Assinatura inválida');
}
});
Resposta Esperada
Sua aplicação deve responder com status 200 OK para indicar que o webhook foi processado com sucesso. Se não recebermos uma resposta 200 dentro de 30 segundos, tentaremos reenviar o webhook.
Tentativas de Reenvio
- Primeira tentativa: Imediatamente após o evento
- Segunda tentativa: 5 minutos depois
- Terceira tentativa: 15 minutos depois
- Quarta tentativa: 1 hora depois
Após 4 tentativas sem sucesso, o webhook será descartado.
Códigos de Status
Webhook processado com sucesso
Erro na estrutura do webhook
