Skip to main content

O que são Webhooks?

Webhooks permitem que a VisePag notifique seu sistema em tempo real quando um evento ocorre — por exemplo, quando um pagamento PIX é confirmado ou um saque é concluído. Em vez de fazer polling constantemente, você configura uma URL e recebe a notificação automaticamente.

Eventos Disponíveis

Os endpoints são cadastrados no Dashboard, no menu Webhooks (URL https://, até 10 endpoints). Na criação você escolhe os eventos (Transações, Saques ou Todos) e recebe o segredo whsec_..., que aparece uma vez só.

Como Responder

Sua URL deve:
  1. Retornar qualquer HTTP 2xx em até 10 segundos
  2. Conferir a assinatura (X-Signature) antes de processar
  3. Processar a lógica de negócio de forma assíncrona

Retentativas

Se sua URL não retornar 2xx ou demorar mais de 10 segundos, a VisePag faz novas tentativas em 30 s, 2 min, 10 min, 30 min, 1 h, 3 h e 6 h. Depois disso, a entrega é dada como falha.
Implemente idempotência no seu handler. O mesmo evento pode ser entregue mais de uma vez. Use o id do evento (header X-Event-Id) para evitar processamento duplicado.

Assinatura

Cada envio é um POST com o corpo {"id", "type", "created_at", "data"} e os headers:

Verificar se é um Evento Novo

Próximos Passos

Referência de Eventos

Veja o payload completo de cada evento disponível