Webhook consulta VPO

Este documento descreve um método alternativo para consulta de Vale-Pedágio Obrigatório (VPO) utilizando webhook, complementando o modelo atual de consulta via API baseada em GUID. O objetivo é permitir que sistemas parceiros recebam automaticamente atualizações de VPO sem a necessidade de realizar consultas periódicas (polling).

Funcionamento geral

O modelo proposto funciona da seguinte forma:

1. Cliente cadastra uma URL de Webhook na plataforma NDD Cargo.
2. Sempre que um dos eventos abaixo ocorrer, o sistema enviará um POST para a URL cadastrada:
   • VPO criado
   • VPO atualizado
   • VPO cancelado
   • Status alterado
3. O cliente recebe o payload, processa e retorna HTTP 200 para confirmar o recebimento.
4. Caso o cliente não responda com sucesso, o NDD Cargo fará retentativas.

Benefícios do modelo por Webhook

• Atualizações recebidas em tempo real
• Menor complexidade para o cliente
• Sincronização mais confiável

dica

Este modelo não substitui a API atual baseada em GUID, mas oferece um mecanismo alternativo mais eficiente para clientes que desejam integração push.

Fluxo de integração

NDD Cargo → dispara evento → envia POST → URL do Cliente → Cliente processa → resposta 200

Cadastro do Webhook

Endpoint de Cadastro

Os clientes poderão cadastrar o webhook pelo seguinte endpoint:

POST /integracoes/webhooks/vpo

Corpo da requisição

{
  "url": "https://cliente.com.br/webhook/vpo/{enterpriseId}",
  "tokenAssinatura": "stringOpcionalParaValidacao",
  "eventos": ["vpo.created", "vpo.updated", "vpo.canceled"]
}

OBS: A função do enterpriseId é identificar a contratante ao qual os eventos será encaminhados através do webhook.

Resposta

{
  "id": "uuid-do-webhook",
  "status": "ativo"
}

Eventos disponíveis

Evento	Descrição
vpo.created	Emitido quando um VPO é criado.
vpo.updated	Emitido quando um VPO é atualizado.
vpo.canceled	Emitido quando um VPO é cancelado.
vpo.statusChanged	Emitido quando o status do VPO é alterado.

observação

Caso novos eventos sejam necessários, basta incluí-los no endpoint de cadastro.

Estrutura do playload

Exemplo de payload enviado no webhook:

{
  "evento": "vpo.updated",
  "dataHora": "2025-01-01T10:12:50Z",
  "vpo": {
    "guid": "3fd31a23-86a1-4d1b-ae20-6fc8d9e47d0e",
    "documento": "12345678901234",
    "valor": 125.90,
    "status": "Aprovado",
    "origem": "SC",
    "destino": "SP",
    "transportador": "NDD Cargo Logística"
  }
}

Segurança

O webhook suportará os seguintes recursos de segurança:

1. Authorization Deve ser enviado o token JWT

Authorization: Bearer {token}

2. Envio via HTTPS Obrigatório

3. Reenvio automático em caso de falha

Política de retentativas:

• 1ª tentativa imediata
• 2ª em 30 segundos
• 3ª em 5 minutos
• 4ª em 30 minutos
• Após isso: marcado como “falha definitiva”

---