Webhooks
Receba notificações automáticas sempre que o status de uma cobrança mudarEm vez de ficar consultando o status de uma transação repetidamente (polling), configure um webhook e a Velfy avisa sua aplicação em tempo real, via
POST, sempre que houver uma mudança.
Como configurar
Basta informar a URL de destino no campopostbackUrl, ao criar a cobrança:
O que esperar na notificação
A Velfy envia um payload JSON contendo o tipo do evento e os dados atualizados da transação — incluindo o status atual, valores pagos/estornados e os dados específicos do método de pagamento usado (QR Code do PIX, linha digitável do boleto, etc).Eventos principais
Como processar corretamente
1
Responda rápido
Retorne
200 OK assim que receber a notificação, antes de processar qualquer lógica de negócio.2
Processe de forma assíncrona
Depois de responder, trate o evento em background (fila, job) — evita timeouts e reentregas desnecessárias.
3
Seja idempotente
O mesmo evento pode ser reentregue mais de uma vez. Use o id da transação para não processar o mesmo pagamento duas vezes.
Boas práticas
Confiabilidade
Confiabilidade
- Armazene o último status processado antes de agir sobre um novo evento
- Monitore falhas de entrega no seu endpoint
Reconciliação
Reconciliação
- Use o endpoint de consulta de transação para conferir o estado real sempre que houver dúvida sobre um evento perdido
Próximos passos
Referência técnica
Veja o payload completo e todos os status possíveis
PIX Out
Envie transferências PIX pela sua conta Velfy