Skip to main content
POST
/
uvvi
/
v1
/
webhook-register
Registrar Webhook
curl --request POST \
  --url https://api.uvvipague.com.br/uvvi/v1/webhook-register \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "url": "https://sua-api.com.br/webhook/uvvipague"
}
'
{
  "request_id": "req_abc123def456",
  "status": "success",
  "message": "Webhook cadastrado com sucesso"
}

​
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

curl --request POST \
  --url 'https://api.uvvipague.com.br/uvvi/v1/webhook-register' \
  --header 'x-api-key: SUA_API_KEY_AQUI' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://sua-api.com.br/webhook/uvvipague"
  }'

​
Resposta de Sucesso

Quando o webhook é registrado com sucesso, você receberá: 
{
  "request_id": "req_abc123def456",
  "status": "success",
  "message": "Webhook cadastrado com sucesso"
}

​
Resposta Esperada do Seu Endpoint

Seu endpoint deve retornar HTTP 200 para confirmar o recebimento: 
HTTP/1.1 200 OK
Content-Type: application/json

{
  "received": true
}
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

# 1. Instale o ngrok
npm install -g ngrok

# 2. Inicie seu servidor local
node server.js  # rodando na porta 3000

# 3. Exponha com ngrok
ngrok http 3000

# 4. Use a URL gerada para cadastrar o webhook
# Exemplo: https://abc123.ngrok.io/webhook/uvvipague

​
Códigos de Resposta HTTP

​
200 - Sucesso

Webhook registrado com sucesso. 
{
  "request_id": "req_abc123def456",
  "status": "success",
  "message": "Webhook cadastrado 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
{
  "success": false,
  "error": "INVALID_REQUEST",
  "message": "URL inválida ou 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
{
  "success": false,
  "error": "WEBHOOK_UNREACHABLE",
  "message": "Não foi possível acessar a URL do webhook"
}

​
Consulta Manual de Status

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

​
Endpoint de Consulta

POST /uvvi/v1/payment/status

// Usando transactionId
const response = await fetch('https://api.uvvipague.com.br/uvvi/v1/payment/status', {
  method: 'POST',
  headers: {
    'x-api-key': 'SUA_API_KEY_AQUI',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    transactionId: 817210768
  })
});

// Ou usando externalId
const response2 = await fetch('https://api.uvvipague.com.br/uvvi/v1/payment/status', {
  method: 'POST',
  headers: {
    'x-api-key': 'SUA_API_KEY_AQUI',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    externalId: "seu-id-interno-123"
  })
});

​
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)

const response = await fetch('https://sandbox-api.uvvipague.com.br/uvvi/v1/webhook-register', {
  method: 'POST',
  headers: {
    'x-api-key': 'sk_test_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://seu-site-dev.com/webhook',
    events: ['debts']
  })
});

​
Produção

const response = await fetch('https://api.uvvipague.com.br/uvvi/v1/webhook-register', {
  method: 'POST',
  headers: {
    'x-api-key': 'sk_live_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://seu-site.com/webhook',
    events: ['debts', 'payment.approved', 'payment.settled']
  })
});

​
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"