> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uvvipague.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Registrar Webhook

> Registra ou atualiza a URL do webhook para receber notificações automáticas de eventos

## 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.

<Info>
  **Configuração via API**: Este endpoint permite configurar webhooks programaticamente, ideal para automação e integração em fluxos de onboarding.
</Info>

## 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

<CardGroup cols={2}>
  <Card title="debts" icon="file-invoice-dollar">
    Débitos encontrados para o veículo consultado
  </Card>

  <Card title="VehicleWithoutDebts" icon="circle-check">
    Veículo sem débitos pendentes
  </Card>

  <Card title="VehicleNotFound" icon="triangle-exclamation">
    Veículo não encontrado no sistema
  </Card>

  <Card title="search-error-event" icon="circle-xmark">
    Erro na consulta (ex: Detran indisponível)
  </Card>
</CardGroup>

### Pagamentos

<CardGroup cols={1}>
  <Card title="payment-status-update" icon="bell">
    Atualizações de status de pagamento (aprovado, recusado, liquidado)
  </Card>
</CardGroup>

<Note>
  **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.
</Note>

## Requisitos da URL

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

### 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

<Tip>
  Durante o desenvolvimento, use ferramentas como [ngrok](https://ngrok.com) para expor seu servidor local e receber webhooks.
</Tip>

## Política de Retentativas

A Uvvipague implementa uma política robusta de retentativas para garantir que você receba as notificações:

<Steps>
  <Step title="Tentativa Inicial">
    Enviamos a primeira requisição imediatamente após o evento ocorrer.
  </Step>

  <Step title="1ª Retentativa - 15 minutos">
    Se não recebermos resposta 200, tentamos novamente após **15 minutos**.
  </Step>

  <Step title="2ª Retentativa - 60 minutos">
    Segunda tentativa após **60 minutos** da tentativa inicial.
  </Step>

  <Step title="3ª Retentativa - 90 minutos">
    Terceira e última tentativa após **90 minutos** da tentativa inicial.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  **Importante**: Após 3 tentativas falhadas, você deve consultar o status do pedido manualmente através da API de consulta de pagamento.
</Warning>

## Exemplo de Uso Completo

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  const requestBody = {
    url: "https://sua-api.com.br/webhook/uvvipague"
  };

  const options = {
    method: 'POST',
    headers: {
      'x-api-key': 'SUA_API_KEY_AQUI',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(requestBody)
  };

  fetch('https://api.uvvipague.com.br/uvvi/v1/webhook-register', options)
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Erro:', error));
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.uvvipague.com.br/uvvi/v1/webhook-register"
  headers = {
      "x-api-key": "SUA_API_KEY_AQUI",
      "Content-Type": "application/json"
  }
  payload = {
      "url": "https://sua-api.com.br/webhook/uvvipague"
  }

  response = requests.post(url, headers=headers, json=payload)
  data = response.json()
  print(data)
  ```

  ```php PHP theme={null}
  <?php
  $curl = curl_init();

  $payload = json_encode([
      "url" => "https://sua-api.com.br/webhook/uvvipague"
  ]);

  curl_setopt_array($curl, [
      CURLOPT_URL => "https://api.uvvipague.com.br/uvvi/v1/webhook-register",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_POSTFIELDS => $payload,
      CURLOPT_HTTPHEADER => [
          "x-api-key: SUA_API_KEY_AQUI",
          "Content-Type: application/json"
      ],
  ]);

  $response = curl_exec($curl);
  curl_close($curl);

  $data = json_decode($response, true);
  print_r($data);
  ?>
  ```
</CodeGroup>

## Resposta de Sucesso

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

```json theme={null}
{
  "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 theme={null}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "received": true
}
```

<Note>
  **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.
</Note>

## Teste de Webhook

### Ferramentas Úteis para Teste

<CardGroup cols={2}>
  <Card title="Webhook.site" icon="globe">
    Use [webhook.site](https://webhook.site) para testar e visualizar webhooks durante o desenvolvimento.
  </Card>

  <Card title="ngrok" icon="tunnel">
    Use [ngrok](https://ngrok.com) para expor seu localhost e receber webhooks em desenvolvimento.
  </Card>

  <Card title="RequestBin" icon="inbox">
    Use [RequestBin](https://requestbin.com) para inspecionar payloads de webhook.
  </Card>

  <Card title="Postman" icon="paper-plane">
    Simule webhooks usando Postman para testar seu endpoint.
  </Card>
</CardGroup>

### Exemplo com ngrok

```bash theme={null}
# 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.

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```http theme={null}
POST /uvvi/v1/payment/status
```

```javascript theme={null}
// 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

<Steps>
  <Step title="Responda Rapidamente">
    Retorne HTTP 200 em menos de 5 segundos. Processe o webhook de forma assíncrona.
  </Step>

  <Step title="Implemente Idempotência">
    Use `transactionId` ou `externalId` para evitar processar o mesmo webhook múltiplas vezes.
  </Step>

  <Step title="Log Tudo">
    Registre todos os webhooks recebidos para auditoria e debugging.
  </Step>

  <Step title="Use Filas">
    Implemente filas (Redis, RabbitMQ, SQS) para processar webhooks de forma resiliente.
  </Step>

  <Step title="Monitore Falhas">
    Configure alertas para webhooks que falharem após todas as retentativas.
  </Step>

  <Step title="Tenha Fallback">
    Implemente consulta periódica de status como fallback caso os webhooks falhem.
  </Step>
</Steps>

## Ambientes

### Sandbox (Teste)

```javascript theme={null}
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

```javascript theme={null}
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

<CardGroup cols={2}>
  <Card title="Receber Webhooks" icon="webhook" href="/api-reference/endpoint/webhook">
    Veja como implementar o endpoint que receberá os webhooks
  </Card>

  <Card title="Consultar Débitos" icon="magnifying-glass" href="/api-reference/endpoint/create">
    Inicie consultas que enviarão webhooks
  </Card>

  <Card title="Processar Pagamentos" icon="credit-card" href="/api-reference/endpoint/payment">
    Processe pagamentos e receba notificações
  </Card>

  <Card title="Documentação de Webhooks" icon="book" href="/webhooks">
    Guia completo sobre webhooks
  </Card>
</CardGroup>

## Suporte

<Card title="Problemas com Registro de Webhook?" icon="headset" href="mailto:suporte@uvvipague.com.br">
  Entre em contato com nosso suporte técnico para ajuda com configuração de webhooks.
</Card>


## OpenAPI

````yaml POST /uvvi/v1/webhook-register
openapi: 3.1.0
info:
  title: Uvvipague API
  description: >-
    API completa para consulta e pagamento de débitos veiculares em todo o
    Brasil
  version: 1.0.0
  contact:
    name: Suporte Uvvipague
    email: suporte@uvvipague.com.br
    url: https://uvvipague.com.br
servers:
  - url: https://api.uvvipague.com.br
    description: Servidor de Produção
  - url: https://api-sandbox.uvvipague.com.br
    description: Servidor de Homologação/Sandbox
security:
  - apiKey: []
tags:
  - name: Veículos
    description: Endpoints para consulta e enriquecimento de informações de veículos
  - name: Débitos
    description: Endpoints para consulta de débitos veiculares
  - name: Pagamentos
    description: Endpoints para processamento de pagamentos
  - name: Webhooks
    description: Endpoints para configuração e gerenciamento de webhooks
paths:
  /uvvi/v1/webhook-register:
    post:
      tags:
        - Webhooks
      summary: Registrar Webhook
      description: >-
        Registra ou atualiza a URL do webhook para receber notificações
        automáticas de eventos
      operationId: registerWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRegisterRequest'
      responses:
        '200':
          description: Webhook registrado com sucesso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookRegisterResponse'
        '400':
          description: Requisição inválida - URL inválida ou eventos não suportados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: URL não pode ser validada ou não responde
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    WebhookRegisterRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: >-
            URL que receberá os webhooks. Deve ser válida e acessível
            publicamente.
          example: https://sua-api.com.br/webhook/uvvipague
    WebhookRegisterResponse:
      type: object
      properties:
        request_id:
          type: string
          description: ID único da requisição
          example: req_abc123def456
        status:
          type: string
          example: success
        message:
          type: string
          example: Webhook cadastrado com sucesso
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - INVALID_REQUEST
                - UNAUTHORIZED
                - NOT_FOUND
                - VALIDATION_ERROR
                - RATE_LIMIT_EXCEEDED
                - SERVICE_UNAVAILABLE
              example: INVALID_REQUEST
              description: Código do erro
            message:
              type: string
              example: Parâmetros inválidos na requisição
            details:
              type: object
              description: Detalhes adicionais sobre o erro
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API Key fornecida no painel administrativo da Uvvipague

````