Siga-nos nas redes sociais:

Documentação do Webhook

Integre seu sistema com nossa plataforma de rastreamento

Visão Geral

Um webhook é um método de integração que permite que nosso sistema envie dados em tempo real para seu sistema quando um evento específico ocorre.
Através desta integração, você receberá atualizações automáticas sobre a localização e status dos veículos monitorados via requisições POST HTTP.
É importante que seu endpoint responda em no máximo 2 segundos para garantir o correto processamento das notificações. Caso contrário, o sistema considerará como falha e tentará reenviar posteriormente.

Configuração

Para configurar um webhook em sua plataforma, siga os passos abaixo:

  1. Acesse a área administrativa do sistema
  2. Navegue até a seção de configurações de integração
  3. Adicione a URL do endpoint que receberá as notificações
  4. Cadastre o webhook nos veículos desejados
  5. Configure a chave de autenticação (opcional)

Autenticação

Ao cadastrar uma chave de autenticação no webhook, todas as requisições enviadas ao seu endpoint incluirão o header X-Webhook-Key com o valor da chave informada no cadastro.

Se nenhuma chave foi configurada, o header X-Webhook-Key não será enviado. Recomendamos validar esse header no seu endpoint para garantir que a requisição partiu da nossa plataforma.

Exemplo dos headers da requisição quando uma chave está cadastrada:

POST /seu-endpoint HTTP/1.1
Content-Type: application/json
X-Webhook-Key: sua-chave-cadastrada

Exemplo de validação (Node.js + Fastify)

Armazene a chave em variável de ambiente e compare com o header recebido:

const WEBHOOK_KEY = process.env.WEBHOOK_KEY;

fastify.post('/webhook', async (request, reply) => {
    const key = request.headers['x-webhook-key'];

    if (!key || key !== WEBHOOK_KEY) {
        return reply.code(401).send({ error: 'Unauthorized' });
    }

    const payload = request.body;
    // Processar o evento (ex.: atualizar posição do veículo)
    console.log(payload.event, payload.plate, payload.latLong);

    return reply.code(200).send({ received: true });
});

Formato do Payload

Exemplo do JSON que será enviado para seu endpoint:

{
    "event": "POSITION",
    "gpsValid": true,
    "idTracking": 4078139749,
    "ignition": 0,
    "latLong": {
        "latitude": -16.239687,
        "longitude": -47.904413
    },
    "speed": 0,
    "batteryVoltage": 0,
    "odometer": 0,
    "plate": "webhook",
    "driver": "João Silva",
    "externalCode": "",
    "safeAreaName": "casa",
    "date": "2025/03/26 14:43:34"
}

Descrição dos Campos

event

Tipo do evento enviado. No exemplo acima, "POSITION" indica uma atualização de posição do veículo.

gpsValid

Indica se o sinal GPS está válido (true) ou não (false).

idTracking

Identificador único do rastreamento. Este ID pode ser usado para correlacionar eventos do mesmo veículo.

ignition

Status da ignição do veículo. 0 indica que a ignição está desligada, 1 indica que está ligada.

latLong

Objeto contendo as coordenadas geográficas do veículo:

  • latitude: Latitude do veículo
  • longitude: Longitude do veículo

speed

Velocidade atual do veículo em quilômetros por hora (km/h).

batteryVoltage

Nível de tensão da bateria do dispositivo de rastreamento.

odometer

Quilometragem total do veículo.

plate

Placa do veículo monitorado.

driver

Nome do motorista vinculado ao veículo no momento do evento. Será uma string vazia se nenhum motorista estiver associado.

externalCode

Código externo opcional que pode ser usado para identificação adicional do veículo ou dispositivo.

safeAreaName

Nome da cerca eletrônica onde o veículo está localizado. Será null se o veículo não estiver em nenhuma área definida.

date

Data e hora do evento no formato YYYY/MM/DD HH:mm:ss.

Recomendações de Segurança

HTTPS

Utilize HTTPS para todas as URLs de webhook

Autenticação

Valide o header X-Webhook-Key com a chave cadastrada no webhook

Validação

Valide a origem das requisições

Manutenção

Mantenha os endpoints atualizados e seguros