Skip to main content
POST
Registrar Webhook

Descrição

Registra ou atualiza a URL do webhook para receber notificações automáticas sobre eventos da API, como consultas de débitos concluídas, pagamentos aprovados e liquidação de débitos.
Configuração via API: Este endpoint permite configurar webhooks programaticamente, ideal para automação e integração em fluxos de onboarding.

Por Que Usar Webhooks?

Os webhooks eliminam a necessidade de polling constante da API, permitindo que você:
  • Receba notificações em tempo real sobre eventos importantes
  • Reduza o número de requisições à API
  • Melhore a experiência do usuário com atualizações instantâneas
  • Processe eventos de forma assíncrona e eficiente

Eventos Disponíveis

Você receberá webhooks para os seguintes tipos de eventos:

Consulta de Débitos

debts

Débitos encontrados para o veículo consultado

VehicleWithoutDebts

Veículo sem débitos pendentes

VehicleNotFound

Veículo não encontrado no sistema

search-error-event

Erro na consulta (ex: Detran indisponível)

Pagamentos

payment-status-update

Atualizações de status de pagamento (aprovado, recusado, liquidado)
Campo externalId: Todos os webhooks incluem o campo externalId que você enviou na requisição original. Use este campo para correlacionar webhooks com suas requisições. Se você não enviar um externalId, a API gerará um automaticamente, mas é altamente recomendado que você envie seus próprios IDs únicos.

Requisitos da URL

URL Pública e Acessível: A URL do webhook deve ser válida e acessível publicamente pela internet.

Validações Realizadas

Ao registrar um webhook, a API valida:
  1. Formato da URL: Deve ser uma URL válida e completa
  2. Acessibilidade: A URL deve estar acessível e responder
  3. Tempo de resposta: Deve responder em até 5 segundos
Durante o desenvolvimento, use ferramentas como ngrok para expor seu servidor local e receber webhooks.

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.
Importante: Após 3 tentativas falhadas, você deve consultar o status do pedido manualmente através da API de consulta de pagamento.

Exemplo de Uso Completo

Resposta de Sucesso

Quando o webhook é registrado com sucesso, você receberá:

Resposta Esperada do Seu Endpoint

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.

Teste de Webhook

Ferramentas Úteis para Teste

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

Códigos de Resposta HTTP

200 - Sucesso

Webhook registrado com sucesso.

400 - Bad Request

Dados inválidos na requisição. Possíveis motivos:
  • URL inválida ou mal formatada
  • URL não acessível

422 - Unprocessable Entity

URL válida mas não pode ser acessada. Possíveis motivos:
  • URL não responde
  • Timeout (> 5 segundos)
  • Domínio não existe

Consulta Manual de Status

Se todas as tentativas de webhook falharem, consulte o status manualmente:

Endpoint de Consulta

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.

Ambientes

Sandbox (Teste)

Produção

Próximos Passos

Receber Webhooks

Veja como implementar o endpoint que receberá os webhooks

Consultar Débitos

Inicie consultas que enviarão webhooks

Processar Pagamentos

Processe pagamentos e receba notificações

Documentação de Webhooks

Guia completo sobre webhooks

Suporte

Problemas com Registro de Webhook?

Entre em contato com nosso suporte técnico para ajuda com configuração de webhooks.

Authorizations

x-api-key
string
header
required

API Key fornecida no painel administrativo da Uvvipague

Body

application/json
url
string<uri>
required

URL que receberá os webhooks. Deve ser válida e acessível publicamente.

Example:

"https://sua-api.com.br/webhook/uvvipague"

Response

Webhook registrado com sucesso

request_id
string

ID único da requisição

Example:

"req_abc123def456"

status
string
Example:

"success"

message
string
Example:

"Webhook cadastrado com sucesso"