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

{
  "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"
      }
    }
  }
}

​
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

Horário: Segunda a Sexta, 08h às 18h (BRT) Bug Bounty: Temos programa de recompensas para vulnerabilidades
Dica: Use ferramentas como webhook.site para testar e debuggar seus webhooks durante o desenvolvimento.