Webhooks
Webhooks
Receba notificações automáticas da Pagnovo sempre que algo importante acontecer — como um pagamento aprovado, um saque concluído ou uma cobrança vencida.
Pense em webhooks como mensagens enviadas pela Pagnovo para o seu sistema, sem que você precise ficar consultando a API o tempo todo.
Por que usar webhooks?
Sem webhooks, sua aplicação teria que perguntar para a API a cada segundo:
"Esse pagamento já foi confirmado?"
Isso é lento e ineficiente.
Com webhooks, a Pagnovo avisa você imediatamente:
"O pagamento foi confirmado. Aqui estão os dados."
Assim você pode:
- atualizar o status de um pedido
- liberar acesso a um produto
- enviar e-mails automáticos
- registrar movimentações financeiras
Tudo isso sem precisar fazer nada manualmente, e sem fazer seu cliente esperar.
Como funciona na prática?
- Você cadastra uma URL HTTPS do seu sistema no dashboard.
- Quando um evento acontece, a Pagnovo faz uma requisição
POSTpara essa URL com o payload do evento. - Seu servidor processa, retorna
200 OKe segue a vida. - Se sua URL não responder ou retornar erro, fazemos retry com backoff exponencial por até 24 horas.
| Você faz | A Pagnovo faz |
|---|---|
| Cadastra a URL no dashboard | Envia POST quando um evento acontece |
| Valida assinatura HMAC | Inclui x-signature e x-trace-id nos headers |
Retorna 200 OK | Para de tentar |
Retorna 500 ou dá timeout | Faz retry com backoff |
Próximos passos
Antes de processar webhooks em produção, leia:
- Verificação de assinatura — como validar que o webhook veio mesmo da Pagnovo e não de um atacante que descobriu sua URL.
- Escolhendo uma versão — diferenças entre payload v1 e v2, qual escolher.
- Payload v2 (moderno) — formato recomendado para integrações novas, com eventos tipados e dados de ISPB.