Uma operação que consulta dados de veículos em escala não pode depender de alguém acompanhando uma tela ou executando novas tentativas manualmente. Um webhook de consulta veicular permite que o resultado ou uma mudança relevante seja entregue ao sistema da empresa, no momento em que o evento estiver disponível. A integração deixa de ser uma sequência de verificações ativas e passa a ter um ponto de entrada controlado no seu ambiente.
Isso não elimina a API REST. A consulta continua sendo o mecanismo para solicitar e recuperar dados conforme o serviço contratado. O webhook resolve outro problema: avisar o sistema destinatário sobre um evento, sem exigir polling constante. A separação parece simples, mas define disponibilidade, custo operacional, rastreabilidade e segurança da integração.
O que um webhook de consulta veicular resolve
Em uma integração síncrona, a aplicação envia uma requisição, espera a resposta em JSON e decide o próximo passo. Esse fluxo é adequado quando o resultado cabe no tempo de resposta da jornada, como a pré-análise de um veículo recebido por uma revenda ou a validação de uma garantia antes de avançar um cadastro.
Nem todo processo, porém, deve manter uma conexão aberta até o fim. Há operações que precisam encaminhar o resultado para filas internas, atualizar um dossiê, gerar uma tarefa de conferência ou notificar outro domínio da empresa. Nesses casos, o sistema fornece uma URL HTTPS e recebe uma chamada quando o evento ocorre.
O ganho não está em chamar menos endpoints por princípio. Está em reduzir consultas repetidas sem estado e em tornar o fluxo orientado por eventos. Uma plataforma pode correlacionar cada entrega ao processo de origem, registrar o recebimento e disparar regras próprias sem exigir que o usuário volte ao aplicativo.
Um webhook também não é um canal para colocar toda a decisão de negócio fora do seu controle. Ele entrega uma notificação. A empresa destinatária define como validar a mensagem, armazenar evidências, buscar dados adicionais quando necessário e decidir se um evento deve alterar uma proposta, uma oferta, uma etapa de vistoria ou uma rotina de cobrança.
Arquitetura do webhook de consulta veicular
A arquitetura começa com uma fronteira clara entre o provedor e o sistema cliente. O cliente cadastra um endpoint, por exemplo, uma rota específica do seu domínio. O provedor faz uma requisição HTTP POST para essa rota com o corpo do evento e headers de autenticação. O endpoint confirma o recebimento com uma resposta HTTP de sucesso.
Esse endpoint não deve executar toda a regra de negócio antes de responder. Se ele depender de banco de dados, motores de decisão, serviços internos ou geração de documentos, qualquer lentidão aumenta a chance de timeout e de reentrega. O padrão mais seguro é validar a chamada, persistir a mensagem ou publicá-la em uma fila interna e responder rapidamente. O processamento completo ocorre em um worker separado.
O evento precisa carregar uma chave de correlação. Ela conecta a entrega ao pedido original, ao veículo, à proposta ou ao registro interno da empresa. Não use somente a placa como identificador operacional. A mesma placa pode aparecer em diferentes jornadas, e o dado veicular deve circular sob regras de acesso, retenção e finalidade compatíveis com a operação.
Uma representação simplificada pode seguir esta estrutura:
```json { "event_id": "evt_01H...", "event_type": "vehicle.consultation.completed", "occurred_at": "2026-09-15T14:30:00Z", "correlation_id": "op_8f4c...", "data": { "service": "identificacao_situacao", "status": "completed", "result_reference": "res_23ab..." } } ```
Os nomes acima são ilustrativos. O contrato efetivo deve seguir o schema publicado para o serviço. O ponto central é separar o identificador imutável do evento, o tipo de evento, a data de ocorrência, a correlação de negócio e a referência ao resultado. Essa separação facilita auditoria e evita que o consumidor dependa de campos implícitos.
Webhook não substitui a consulta original
Há uma diferença relevante entre o conteúdo do evento e os dados consultados. Em alguns cenários, o webhook pode trazer o payload necessário para continuidade do processo. Em outros, ele deve trazer apenas uma referência segura para recuperação posterior pela API. A escolha depende do tamanho do retorno, da sensibilidade da informação, das necessidades de retenção e do desenho de permissões da empresa.
Enviar um payload completo reduz uma chamada posterior, mas amplia o perímetro de dados expostos no endpoint receptor e torna o armazenamento do evento mais sensível. Enviar uma referência reduz o conteúdo da notificação, mas exige que o consumidor tenha condições de fazer a leitura autenticada do resultado. Não existe uma opção correta para todos os fluxos.
Segurança: validar antes de processar
Um endpoint público não deve confiar no endereço de origem, no nome de um header ou no formato aparente do JSON. A entrega precisa ser autenticada. Na Lanet, os webhooks são assinados. A assinatura permite que o destinatário valide que a chamada foi produzida por quem conhece o segredo compartilhado e que o corpo não foi alterado em trânsito.
Com HMAC-SHA256, o emissor calcula uma assinatura a partir do corpo bruto da requisição e de um segredo. O destinatário repete o cálculo localmente e compara o resultado. Uma chave vazada sem o segredo não vale nada para produzir uma assinatura válida. A comparação deve ser feita em tempo constante para reduzir vazamento por tempo de execução.
Valide a assinatura sobre os bytes recebidos, antes de desserializar ou reformatar o JSON. Alterar espaços, ordem de campos ou codificação antes do cálculo pode fazer uma entrega legítima parecer inválida. Guarde o segredo em um cofre de credenciais, nunca no código-fonte, em logs ou em variáveis exibidas em ferramentas de observabilidade.
Quando o contrato incluir carimbo de tempo, valide também a janela de aceitação. Isso reduz o risco de replay de uma chamada capturada. O endpoint deve rejeitar mensagens muito antigas ou futuras fora da tolerância definida e registrar o motivo da rejeição sem salvar o conteúdo sensível em texto aberto.
A segurança não termina no HMAC. Restrinja o endpoint a HTTPS, imponha limites de tamanho de corpo, trate JSON inválido como erro de cliente e aplique controle de acesso aos registros internos que armazenam eventos. Também vale separar segredos por ambiente: tráfego de teste e produção não devem compartilhar credenciais nem destinos.
Idempotência evita efeitos duplicados
Entrega única não é uma premissa segura em sistemas distribuídos. Se o emissor não receber a confirmação HTTP, ele pode reenviar a mesma mensagem mesmo que o seu sistema já tenha processado a primeira tentativa. Falhas de rede, timeout e reinício de processo produzem esse comportamento sem indicar erro no dado.
Por isso, o consumidor deve tratar o `event_id` como chave de idempotência. Antes de executar qualquer efeito - criar uma pendência, avançar uma proposta, emitir um documento ou enviar uma notificação - registre que aquele evento foi recebido. Se ele reaparecer, responda com sucesso e não repita a ação de negócio.
A idempotência precisa estar perto do efeito que ela protege. Uma tabela de eventos recebidos com restrição de unicidade costuma ser mais confiável do que uma variável em memória. Em operações de maior criticidade, associe a deduplicação à transação que altera o estado interno. Assim, a empresa evita o cenário em que marca o evento como processado, mas falha antes de atualizar a proposta.
Também trate eventos fora de ordem. Um evento posterior pode chegar antes de outro por causa de retentativas ou filas diferentes. O consumidor deve considerar data de ocorrência, versão do estado e regras explícitas de transição, em vez de assumir que a ordem de chegada é a ordem dos fatos.
Respostas HTTP e retentativas
A resposta do endpoint comunica se a entrega foi aceita, não se toda a jornada foi concluída. Retorne um código 2xx apenas depois de validar a assinatura e garantir a persistência ou o enfileiramento da mensagem. Se o serviço interno estiver indisponível e não houver como reprocessar a entrega, responder sucesso apenas para encerrar a tentativa cria perda silenciosa.
Erros permanentes, como assinatura inválida ou payload fora do schema aceito, devem ser observáveis e tratados como falha de validação. Erros transitórios, como indisponibilidade temporária do banco ou da fila, devem produzir uma resposta que permita nova tentativa conforme o contrato do webhook. A política de retentativa, os limites e o comportamento após esgotamento precisam estar documentados antes da entrada em produção.
O mesmo vale para timeouts. Defina um limite de processamento curto no endpoint de borda e meça latência, taxa de respostas não 2xx, eventos duplicados, falhas de assinatura e idade da fila. Esses sinais mostram se a integração está recebendo eventos, mas não conseguindo transformá-los em trabalho concluído.
Como colocar o fluxo em produção
Antes de habilitar um webhook de consulta veicular, modele o evento a partir de uma pergunta operacional: qual decisão depende dele e qual sistema é responsável por executá-la? Essa resposta define a chave de correlação, o nível de dados no payload e a retenção necessária para auditoria.
Depois, implemente o endpoint com validação de assinatura, deduplicação persistente e enfileiramento. Teste cenários que costumam ser ignorados: entrega duplicada, corpo alterado, segredo incorreto, evento atrasado, indisponibilidade da fila e processamento fora de ordem. Chaves de teste da Lanet, identificadas pelo prefixo `lnt_test_`, não são cobradas e permitem separar esse trabalho do ambiente produtivo.
Por fim, alinhe engenharia, operações e compliance sobre o que é registrado. Um log útil contém identificadores técnicos, horário, resultado da validação e estado de processamento. Ele não precisa replicar dados cadastrais ou informações além do necessário para investigar uma falha.
O webhook bem implementado não é só uma URL que recebe POST. Ele vira uma fronteira auditável entre a consulta veicular e a decisão operacional. Quando assinatura, idempotência e observabilidade entram no desenho inicial, o time consegue evoluir o fluxo sem transformar cada reentrega em um incidente.
