Visão Geral
Webhooks permitem que sua aplicação receba notificações automáticas quando eventos importantes ocorrem na API Uvvipague, como mudanças de status de pagamento, liquidação de débitos e conclusão de consultas.Comunicação Assíncrona: Os webhooks são enviados de forma assíncrona. Configure sua URL para receber as notificações automaticamente.
Correlacionando Requisições e Webhooks: Todos os webhooks incluem o campo
externalId que você enviou na requisição original. Use este campo para identificar qual requisição gerou cada webhook. Se você não enviar um externalId, a API gerará um automaticamente, mas é altamente recomendado que você envie seus próprios IDs únicos.Cadastro de Webhook
Endpoint
Parâmetros
string
required
URL do endpoint que receberá as notificações webhook. Deve ser uma URL válida e acessível publicamente.Exemplo:
https://sua-api.com.br/webhook/uvvipagueHeaders Obrigatórios
string
required
Sua API Key para autenticação
Exemplo de Requisição
Resposta de Sucesso
Política de Retentativas
A Uvvipague implementa uma política robusta de retentativas para garantir que você receba as notificações:1
Tentativa Inicial
Enviamos a primeira requisição imediatamente após o evento ocorrer.
2
1ª Retentativa - 15 minutos
Se não recebermos resposta 200, tentamos novamente após 15 minutos.
3
2ª Retentativa - 60 minutos
Segunda tentativa após 60 minutos da tentativa inicial.
4
3ª Retentativa - 90 minutos
Terceira e última tentativa após 90 minutos da tentativa inicial.
5
Após 3 Retentativas
Após as 3 retentativas sem sucesso, nenhuma nova tentativa será realizada.O cliente precisará consultar o status manualmente usando o
transactionId ou o externalId enviado na requisição original.Timeline de Retentativas
Recebendo Webhooks
Estrutura do Payload
Quando um evento ocorre, enviamos uma requisição POST para sua URL cadastrada:- Débitos Encontrados
- Veículo Sem Débitos
- Veículo Não Encontrado
- Erro na Consulta
- Pagamento Aprovado
Resposta Esperada
Seu endpoint deve retornar HTTP 200 para confirmar o recebimento:Importante: Retorne 200 o mais rápido possível. Processe o webhook de forma assíncrona em sua aplicação para não bloquear a resposta.
Implementação do Endpoint
Exemplo Completo
Segurança
Validações Recomendadas
Validar Origem
Validar Origem
Valide que a requisição vem dos servidores da Uvvipague:
- Verifique o IP de origem (lista fornecida pelo suporte)
- Implemente whitelist de IPs
Validar Estrutura
Validar Estrutura
Valide a estrutura do payload antes de processar:
Idempotência
Idempotência
Implemente idempotência usando
transactionId ou externalId:Timeout Adequado
Timeout Adequado
Configure timeout adequado no seu servidor:
- Responda em menos de 5 segundos
- Processe de forma assíncrona
- Use filas (Redis, RabbitMQ) para processamento
Consulta Manual de Status
Se todas as tentativas de webhook falharem, consulte o status manualmente:Endpoint de Consulta
Testando Webhooks
Ferramentas Úteis
Webhook.site
Use webhook.site para testar e visualizar webhooks durante o desenvolvimento.
ngrok
Use ngrok para expor seu localhost e receber webhooks em desenvolvimento.
RequestBin
Use RequestBin para inspecionar payloads de webhook.
Postman
Simule webhooks usando Postman para testar seu endpoint.
Exemplo com ngrok
Boas Práticas
1
Responda Rapidamente
Retorne HTTP 200 em menos de 5 segundos. Processe o webhook de forma assíncrona.
2
Implemente Idempotência
Use
transactionId ou externalId para evitar processar o mesmo webhook múltiplas vezes.3
Log Tudo
Registre todos os webhooks recebidos para auditoria e debugging.
4
Use Filas
Implemente filas (Redis, RabbitMQ, SQS) para processar webhooks de forma resiliente.
5
Monitore Falhas
Configure alertas para webhooks que falharem após todas as retentativas.
6
Tenha Fallback
Implemente consulta periódica de status como fallback caso os webhooks falhem.
Próximos Passos
Fluxo Completo
Veja como integrar webhooks no fluxo completo
Consulta de Débitos
Entenda os tipos de resposta via webhook
ENUMs e Tipos
Consulte os tipos de eventos e status
Autenticação
Configure sua API Key