Skip to main content
Os webhooks da API Avantti Finance permitem que sua aplicação receba notificações automáticas quando eventos importantes acontecem em sua conta, como pagamentos recebidos, transferências concluídas e mudanças de status.

​
🚀 Como Funcionam

Os webhooks são enviados automaticamente via POST para as URLs que você configurar sempre que eventos relevantes ocorrem em sua conta. Isso elimina a necessidade de fazer polling constante na API.

​
Vantagens dos Webhooks

⚡ Tempo Real

Receba notificações instantâneas sobre mudanças importantes

🔄 Confiabilidade

Sistema de retry automático para garantir entrega

📊 Flexibilidade

Configure diferentes endpoints para diferentes tipos de evento

​
📡 Eventos Disponíveis

​
🔹 Eventos de Transação (PIX IN)

EventoDescriçãoQuando é enviado
transaction_createdTransação criadaQR Code gerado com sucesso
transaction_paidTransação pagaPIX recebido e confirmado
transaction_refundedTransação estornadaEstorno processado
transaction_infractionInfração na transaçãoProblemas detectados pelo BC

​
🔹 Eventos de Transferência (PIX OUT)

EventoDescriçãoQuando é enviado
transfer_createdTransferência criadaTransferência iniciada
transfer_completedTransferência concluídaPIX enviado com sucesso
transfer_canceledTransferência canceladaTransferência cancelada
transfer_updatedTransferência atualizadaStatus alterado

​
📋 Estrutura dos Webhooks

​
Webhook de Transação (PIX IN)

{
  "id": "wh_64f8a2b1c3d4e5f6g7h8i9j0",
  "type": "transaction",
  "event": "transaction_paid",
  "scope": "user",
  "transaction": {
    "id": "clm8x9y0z1234567890abcdef",
    "amount": 29990,
    "status": "paid",
    "pix": {
      "endToEndId": "E12345678202412011030567890AB123C",
      "payerInfo": {
        "name": "Maria Silva Santos",
        "document": "12345678901"
      }
    }
  }
}

​
Webhook de Transferência (PIX OUT)

{
  "id": "wh_75g9b3c2d4e5f6g7h8i9j0k1",
  "type": "transfer",
  "event": "transfer_completed",
  "scope": "user",
  "transfer": {
    "id": "cln1a2b3c4567890defghijk",
    "amount": 150000,
    "status": "completed",
    "pix": {
      "endToEndId": "E87654321202412011145543210ZY987X",
      "creditorAccount": {
        "bank": "341",
        "branch": "1234",
        "account": "567890"
      }
    }
  }
}

​
🔄 Sistema de Retry

Se seu endpoint não responder com status 200, implementamos um sistema de retry automático:
  • 1ª tentativa: Imediatamente
  • 2ª tentativa: Após 1 minuto
  • 3ª tentativa: Após 5 minutos
  • 4ª tentativa: Após 15 minutos
  • 5ª tentativa: Após 1 hora
Após 5 tentativas sem sucesso, o webhook é marcado como falhado e você pode visualizar no dashboard.

​
📊 Monitoramento

​
Dashboard de Webhooks

No seu dashboard você pode:
  • Ver histórico de webhooks enviados
  • Verificar status de entrega
  • Reenviar webhooks falhados
  • Visualizar logs detalhados

​
Logs Úteis

// Log estruturado para debugging
console.log({
  timestamp: new Date().toISOString(),
  webhookId: event.id,
  eventType: event.event,
  processed: true,
  processingTime: Date.now() - startTime
})

​
🚨 Troubleshooting

​
Problemas Comuns

  • Verifique se a URL está acessível publicamente
  • Confirme se está respondendo com status 200
  • Teste com ferramentas como ngrok para desenvolvimento local
  • Verifique se não há firewall bloqueando
  • Confirme se está usando o signatureSecret correto
  • Verifique se o payload não foi modificado
  • Use o body raw da requisição para verificação
  • Certifique-se de usar UTF-8 encoding
  • Implemente processamento idempotente
  • Use o id do evento para deduplicação
  • Armazene IDs processados em cache/banco
  • Sempre responda 200 para eventos já processados

​
📞 Suporte

Para configurar webhooks ou resolver problemas: Email: [email protected]
WhatsApp: +55 31 98266-2897
Documentação: Gerenciar Webhooks
Dica: Use ferramentas como webhook.site para testar e debuggar seus webhooks durante o desenvolvimento.
teste