Guia

Webhooks

4 min de leituraVale para v1

Webhooks permitem que a API Frota162 avise seu sistema automaticamente quando algo acontece na sua frota — sem precisar consultar a API repetidamente. Sempre que um evento ocorre, a API faz um POST para a URL cadastrada com os dados do evento em JSON.

A entrega é garantida pelo menos uma vez (at-least-once): o mesmo evento pode chegar mais de uma vez. Trate os eventos de forma idempotente — veja Operação e monitoramento.

Esta documentação está dividida em três partes:

Página	Responde
Esta página	Como eu ligo isso? — credenciais, requisitos, autenticação, cadastro e teste
Eventos e payloads	O que vem no corpo de cada evento?
Operação e monitoramento	Está no ar — e agora? Duplicatas, falhas, reenvio

Pré-requisito: credenciais de API

O envio de webhooks depende das credenciais de API (ACCESS_TOKEN e SECRET_KEY) do seu usuário. Elas vão nos headers Authorization e Key de cada requisição de webhook — é com elas que seu sistema confirma que o evento veio da Frota162 (veja Autenticação do webhook). Sem as credenciais geradas, os webhooks não são enviados.

Gere as duas no painel do ambiente que vai usar:

Acesse Configurações → Usuários ou Gestão → Usuários no menu lateral.
Abra a edição do seu próprio usuário.
Na seção Credenciais de API, use os botões Gerar Token e Gerar Secret Key.

O passo a passo completo, com os endereços de sandbox e produção, está em Introdução e Primeiros Passos.

Gerar novas credenciais muda a assinatura

Se você gerar um novo ACCESS_TOKEN ou uma nova SECRET_KEY, os webhooks passam a chegar com os novos valores nos headers. Atualize as credenciais usadas na validação do seu endpoint, ou os eventos serão recusados pela sua checagem de assinatura.

Requisitos do endpoint

Antes de cadastrar, seu endpoint precisa atender a todos os critérios abaixo. O cadastro rejeita URLs que não atendam aos três primeiros; os demais não bloqueiam o cadastro, mas causam falhas de entrega.

Requisito	Detalhe
HTTPS obrigatório	URLs `http://` são rejeitadas no cadastro
Host público	Endereços privados, de loopback ou reservados são rejeitados: `localhost`, `127.0.0.1`, faixas `10.x`, `172.16–31.x`, `192.168.x`, `169.254.x`, IPv6 `::1` e faixas privadas
Hostname resolvível	O domínio precisa resolver para um IP público válido
HTTP 200 em menos de 5 segundos	Se o processamento for demorado, responda primeiro e processe depois, em fila — código em Responda rapidamente
Aceitar POST com JSON	O corpo chega como `Content-Type: application/json`

IPs de origem

Os webhooks são enviados a partir dos seguintes IPs. Se você usa allowlist de IP no firewall, libere os quatro:

84.24.3
234.9.54
231.115.63
227.129.114

Autenticação do webhook

Cada requisição de webhook inclui os mesmos headers de autenticação HMAC usados nas chamadas da API:

Authorization: Basic {SEU_ACCESS_TOKEN}
Key: {ASSINATURA_HMAC}
Content-Type: application/json

Sem conferir o header Key, qualquer um que descubra a sua URL consegue injetar eventos falsos no seu sistema. Valide no recebimento:

const crypto = require('crypto');

app.post('/webhooks/frota162', (req, res) => {
  const keyHeader = req.headers['key'];

  const assinaturaEsperada = crypto
    .createHmac('sha256', process.env.FROTA_SECRET_KEY)
    .update(process.env.FROTA_ACCESS_TOKEN)
    .digest('hex');

  if (keyHeader !== assinaturaEsperada) {
    return res.status(401).send('Não autorizado');
  }

  res.status(200).send('OK');
});

Use comparação de tempo constante

Em produção, prefira crypto.timingSafeEqual na comparação da assinatura para evitar ataques de timing.

Cadastre o webhook via API

Prepare o endpoint antes de cadastrar

Cadastrar um webhook com a mesma url + event_id de outro já existente devolve fbk_008, e não existe rota de atualização nem de exclusão — corrigir uma URL errada depende do suporte. Confirme que o endpoint está de pé e validando a assinatura antes de registrá-lo.

Localize o event_id do que você quer receber no catálogo de eventos — é um cadastro por event_id, e você pode registrar vários numa só chamada enviando um array.

POST/key/webhooks/add

curl -X POST \
  https://apidev.v1.frota162.com.br/key/webhooks/add \
  -H 'Authorization: Basic SEU_ACCESS_TOKEN' \
  -H 'Key: SUA_ASSINATURA_HMAC' \
  -H 'cache-control: no-cache' \
  -d '[{
    "url": "https://seu-sistema.com/webhooks/frota162",
    "event_id": 1,
    "company_id": 123
  }]'

Resposta de sucesso:

{
  "events": [
    {
      "result": {
        "url": "https://seu-sistema.com/webhooks/frota162",
        "event_id": "1",
        "client_id": "123",
        "id": 456
      },
      "code": 201
    }
  ],
  "error": false,
  "code": "fbk_200"
}

Teste o recebimento

Depois de cadastrar o webhook, você pode disparar um evento de teste diretamente pelo sistema Frota162 — sem esperar um evento real acontecer e sem precisar abrir chamado no suporte. O disparo envia um payload com dados fictícios do tipo de evento configurado.

Acesse o perfil da empresa no sistema Frota162.
Role a página até a seção Webhooks.
Localize o webhook cadastrado. Ao lado do botão Logs, clique em Testar webhook.
Confira no seu endpoint se o POST chegou — com os headers Authorization e Key e o corpo no formato esperado (veja Eventos e payloads).

Dados fictícios

O disparo de teste serve apenas para validação de conexão. Os dados enviados são fictícios e não correspondem a multas, notificações ou veículos reais.

Não recebeu o evento?

Verifique os erros de entrega em Operação e monitoramento e confirme os requisitos do endpoint.

Próximos passos

WebhooksEventos e payloads

Catálogo completo de eventos e a estrutura do corpo de cada um.

WebhooksOperação e monitoramento

Duplicatas, filas, erros de entrega e reenvio.

AutenticaçãoAutenticação HMAC

Como calcular a assinatura usada na validação.

Pré-requisito: credenciais de API​

Requisitos do endpoint​

IPs de origem​

Autenticação do webhook​

Cadastre o webhook via API​

Teste o recebimento​

Próximos passos​