Pular para o conteúdo principal

Webhooks

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.

Tipos de eventos​

EventoIDDescrição
Nova multa cadastrada1Quando uma infração é registrada
Atualização de multa2Quando uma infração é atualizada
Nova notificação cadastrada3Quando uma notificação de infração é registrada
Atualização de notificação4Quando uma notificação é atualizada
Taxa de IPVA5Quando uma taxa de IPVA é registrada
Taxa de DPVAT6Quando uma taxa de DPVAT é registrada
Taxa de licenciamento7Quando uma taxa de licenciamento é registrada
Cronotacógrafo8Quando um certificado de cronotacógrafo é atualizado
Dados de veículo novos9Quando novos dados de um veículo são consultados
Atualização de dados de veículo10Quando dados de veículo são atualizados

Segurança dos webhooks​

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

Valide esses headers no seu servidor para garantir que o webhook veio da Frota162. O código de validação está na seção Boas práticas abaixo.

IPs de origem​

Os webhooks são enviados a partir dos seguintes IPs:

18.234.9.54
35.231.115.63
34.227.129.114

Configure seu firewall para aceitar requisições desses IPs caso use allowlisting de IPs no seu servidor.

Cadastrar webhook via API​

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
  }]'

Você pode cadastrar múltiplos webhooks no mesmo request enviando um array de objetos.

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"
}
Duplicatas não são atualizadas — não existe rota de atualização

Enviar um webhook com a mesma url + event_id de um já cadastrado retorna erro fbk_008 — a entrada existente não é sobrescrita. A API não expõe rota de atualização ou exclusão de webhooks.

Estrutura dos payloads​

event_type: "frame"

{
  "event_type": "frame",
  "id": 1,
  "company_id": 1,
  "car": {
    "car_id": 1,
    "car_plate": "ABC1234"
  },
  "frame": {
    "ait": "R1111111",
    "type": "MULTA",
    "at": "2024-01-11",
    "time": "20:26:00",
    "expiration_at": "2024-03-02",
    "code": "74550",
    "description": "TRANSITAR EM VELOCIDADE SUPERIOR A MAXIMA PERMITIDA EM ATE 20%",
    "address": "RUA AFONSO GARBUIO, N. 790",
    "city": null,
    "state": null,
    "points": 4,
    "amount": 130.16,
    "discount_amount": 104.13,
    "driver_indicate": 0
  },
  "organization": {
    "organization_code": 1,
    "organization_name": "ORG"
  },
  "driver": {
    "id": null,
    "name": null,
    "indicate": null
  },
  "payment": {
    "at": null,
    "amount": 0
  },
  "created_at": "2024-04-05T20:49:18.000Z",
  "updated_at": null
}

O campo driver_indicate indica se o condutor já foi identificado: 0 = não indicado, 1 = indicado.

Boas práticas no recebimento​

Responda rapidamente​

Seu endpoint deve responder com HTTP 200 em menos de 5 segundos. Se o processamento for demorado, salve o payload em fila e processe de forma assíncrona.

app.post('/webhooks/frota162', async (req, res) => {
  // Responda imediatamente
  res.status(200).send('OK');

  // Processe de forma assíncrona
  await fila.adicionar(req.body);
});

Valide a autenticação​

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');
});

Trate duplicatas​

A Frota162 pode reenviar o mesmo webhook em caso de falha. Use o id do evento para detectar e ignorar duplicatas.

const eventosProcessados = new Set();

app.post('/webhooks/frota162', async (req, res) => {
  const { id, event_type } = req.body;
  const chave = `${event_type}_${id}`;

  if (eventosProcessados.has(chave)) {
    return res.status(200).send('Já processado');
  }

  eventosProcessados.add(chave);
  // ... processar evento
  res.status(200).send('OK');
});

Monitorar e reenviar webhooks​

Quando seu servidor retorna erro ou não responde dentro do limite de tempo, a entrega falha e fica registrada no log de erros. Use os endpoints abaixo para inspecionar falhas e reprocessá-las sem precisar aguardar que o evento ocorra novamente.

Listar erros de entrega​

Retorna os webhooks que não foram entregues com sucesso. Cada entrada inclui o id do log de erro (necessário para reenvio), a URL de destino, o payload que falhou e o código de resposta recebido (ou o motivo do timeout).

GET /key/webhooks-errors?pagination[page]=1&pagination[perpage]=50

curl -X GET \
  'https://apidev.v1.frota162.com.br/key/webhooks-errors?pagination[page]=1&pagination[perpage]=50' \
  -H 'Authorization: Basic SEU_ACCESS_TOKEN' \
  -H 'Key: SUA_ASSINATURA_HMAC' \
  -H 'cache-control: no-cache'

Reenviar um webhook com erro​

Reprocessa uma entrega específica usando o id retornado pelo endpoint de listagem acima.

POST /key/webhooks/logs/{evento_id}/resend

curl -X POST \
  https://apidev.v1.frota162.com.br/key/webhooks/logs/123/resend \
  -H 'Authorization: Basic SEU_ACCESS_TOKEN' \
  -H 'Key: SUA_ASSINATURA_HMAC' \
  -H 'cache-control: no-cache'

Substitua 123 pelo id do log de erro obtido na listagem acima.

Próximos passos​

Quero...Ir para...
Entender os códigos de erro da APITratamento de Erros
Ver o guia completo de integraçãoIntrodução