O que são Webhooks e como utilizar?

O que é um Webhook?

Um webhook é uma forma de a Cobli avisar automaticamente o seu sistema sempre que algo importante acontecer com os seus veículos — sem que você precise ficar perguntando.

Imagine que você tem um sistema próprio de gestão e quer saber exatamente quando um veículo entrou em um depósito, ligou o motor ou ultrapassou o limite de velocidade. Com o webhook, a Cobli envia essa informação diretamente para o seu sistema no momento em que o evento ocorre, em tempo real.

Atenção: para receber os eventos, é necessário ter um endpoint HTTP (uma espécie de "porta" no seu sistema) que aceite requisições do tipo POST. Se você não tem uma equipe técnica, fale com o seu time de TI ou com o desenvolvedor responsável pelo seu sistema.

 

Como funciona?

O funcionamento é simples:

1. A Cobli detecta um evento na frota (ex: veículo ligou o motor).
2. A Cobli envia automaticamente uma mensagem com os detalhes do evento para a URL que você configurou.
3. O seu sistema recebe essa mensagem e pode fazer o que precisar: salvar no banco de dados, disparar um alerta, atualizar um painel, etc.

 

Como cadastrar e começar a receber?

Acesse o painel da Cobli e siga os passos:

1. Clique em Configurações no menu principal.
2. Vá até a aba Webhooks.
3. Clique em Criar Webhook.
4. Informe a URL do seu endpoint, a chave secreta (usada para validar que o envio veio realmente da Cobli) e os tipos de eventos que deseja receber.

Cada assinatura pode receber um ou mais tipos de eventos. Você pode criar múltiplas assinaturas com URLs diferentes, caso precise direcionar eventos para sistemas distintos.

 

Quais eventos estão disponíveis?

A Cobli oferece uma variedade de eventos para monitorar diferentes situações da sua frota:

 

Pontos de Interesse (Geofence)

Notifica quando um veículo entra ou sai de um local cadastrado.

Evento	Descrição
Entrada em local de interesse	O veículo chegou a um ponto de interesse cadastrado
Saída de local de interesse	O veículo saiu de um ponto de interesse cadastrado

 

Ignição

Notifica mudanças no estado da ignição do veículo.

Evento	Descrição
Ignição ligada	O veículo foi ligado
Ignição desligada	O veículo foi desligado

 

Posição do Veículo

Envio periódico da localização do veículo.

Evento	Descrição
Posição (ignição ligada)	Localização enviada periodicamente enquanto o veículo está em movimento
Posição (ignição desligada)	Localização enviada periodicamente enquanto o veículo está parado

 

Velocidade

Alertas de excesso de velocidade — ao se cadastrar neste evento, você recebe automaticamente o início e o fim do alerta.

Evento	Descrição
Início de excesso de velocidade	O veículo ultrapassou o limite de velocidade configurado
Fim de excesso de velocidade	O veículo voltou ao limite, indicando a duração total do alerta

 

Bateria

Notificações sobre o estado da bateria externa do veículo.

Evento	Descrição
Bateria fraca	A tensão da bateria caiu abaixo do limite configurado
Bateria desconectada	A bateria externa foi desconectada do dispositivo
Bateria reconectada	A bateria externa foi reconectada ao dispositivo

 

Eventos de Câmera

Disponíveis apenas para frotas com dispositivos Cobli com câmera integrada. A disponibilidade de cada evento depende do modelo do dispositivo instalado.

Evento	Descrição
Frenagem brusca	Frenagem intensa detectada pela câmera
Aceleração brusca	Aceleração agressiva detectada pela câmera
Curva acentuada	Curva em alta velocidade detectada pela câmera
Seguimento próximo	Veículo muito próximo do da frente (tailgating)
Aviso de colisão frontal	Risco de colisão detectado pela câmera
Distração ao volante	Motorista distraído detectado pela câmera
Olhos fechados	Motorista com olhos fechados (sonolência)
Uso de celular	Motorista usando celular ao volante
Uso de cigarro	Motorista fumando dentro do veículo
Bocejo	Bocejo detectado (possível fadiga)
Sinal SOS	O motorista acionou o botão de emergência

 

Como é o formato das mensagens enviadas?

Cada evento enviado pela Cobli segue o mesmo padrão, com quatro campos principais:

Campo	O que significa
eventId	Identificador único do evento. Pode ser usado para evitar duplicidades.
eventTime	Data e hora em que o evento ocorreu (formato internacional UTC).
eventType	Tipo do evento (ex: geofence_in, ignition_on, speed, etc.).
eventData	Detalhes do evento: placa, localização, velocidade, identificação do motorista, etc.

 

Informações presentes nos detalhes do evento (eventData)

Os eventos contêm diversas informações sobre o veículo e o momento do ocorrido:

Informação	Descrição	Sempre presente?
ID do dispositivo	Identificador do rastreador instalado no veículo	Sim
ID do veículo	Identificador do veículo na Cobli	Sim
ID da frota	Identificador da frota	Sim
Placa	Placa do veículo	Sim
ID do motorista	Quando o motorista está identificado no sistema	Não
Latitude / Longitude	Localização no momento do evento	Não
Velocidade (km/h)	Velocidade no momento do evento	Não
Ignição	Estado da ignição (Ligada ou Desligada)	Não
Odômetro (km)	Quilometragem do veículo (requer configuração prévia)	Não
Tensão da bateria	Tensão em milivolts	Não
Nível de combustível	Apenas em veículos com rede CAN	Não
RPM do motor	Apenas em veículos com rede CAN	Não
Tipo de conexão	Rede utilizada pelo dispositivo (ex: 4G LTE)	Não
Satélites GPS	Quantidade de satélites captados no momento	Não

Campos não obrigatórios podem estar ausentes dependendo do modelo do dispositivo e da disponibilidade do dado no momento do evento. O seu sistema deve estar preparado para lidar com informações faltantes.

 

Como garantir que as mensagens são realmente da Cobli?

Cada requisição enviada pela Cobli inclui uma assinatura digital no cabeçalho X-Cobli-Signature. Essa assinatura é gerada com base na chave secreta que você configurou no painel.

Antes de processar qualquer evento, o seu sistema deve verificar essa assinatura para garantir que a mensagem é legítima. Mensagens sem assinatura válida devem ser rejeitadas.

Solicite ao seu time de TI que implemente a validação da assinatura HMAC-SHA256. A documentação técnica completa está disponível em docs.cobli.co/docs/webhooks.

 

O que acontece se o meu sistema não receber um evento?

A Cobli possui um sistema automático de reenvio para garantir a entrega dos eventos:

 

Comportamento por tipo de resposta

Resposta do seu sistema	O que a Cobli faz
Confirmação (código 2xx)	Entrega confirmada — não reenvia
Erro do seu sistema (código 5xx)	Reenvia automaticamente com intervalos crescentes
Sem resposta em 5 segundos (timeout)	Reenvia automaticamente com intervalos crescentes
Muitas requisições (código 429)	Reenvia após o intervalo indicado pelo seu sistema
Erro de configuração (código 4xx)	Não reenvia — considera como falha permanente

 

Política de reenvio

A Cobli tenta entregar o evento até 5 vezes, com intervalos crescentes:

• 1ª tentativa extra: aguarda 2 segundos
• 2ª tentativa extra: aguarda 4 segundos
• 3ª tentativa extra: aguarda 8 segundos
• 4ª e 5ª tentativas: aguarda 15 segundos cada

 

Pausa automática

Se o seu sistema falhar 5 vezes seguidas, a Cobli pausa os envios para aquela URL por 60 segundos e retoma automaticamente depois. Apenas a URL com problemas é afetada — outras assinaturas continuam funcionando normalmente.

 

Desativação automática

Se os envios continuarem falhando por 7 dias consecutivos, a assinatura é desativada automaticamente. Nenhum evento será entregue até que você reative a assinatura no painel da Cobli.

Importante: eventos gerados durante o período de inatividade não são reprocessados após a reativação.

 

Boas práticas para o seu time técnico

• Responda rápido, processe depois: o seu endpoint deve confirmar o recebimento em até 5 segundos. Se o processamento for demorado, faça-o em segundo plano.
• Evite duplicidades: use o campo eventId como chave de idempotência — o mesmo evento pode chegar mais de uma vez em caso de reenvio.
• Valide sempre a assinatura: rejeite qualquer requisição sem o header X-Cobli-Signature válido.
• Não retente erros 4xx: a Cobli interpreta esses erros como falhas permanentes e não fará novos envios. Corrija a integração e aguarde novos eventos.
• Ignore tipos desconhecidos sem erro: se receber um eventType não esperado, retorne 2xx em vez de erro para evitar desativações desnecessárias.
• Monitore a saúde da integração: fique de olho no campo failure_started_at para identificar problemas antes dos 7 dias que resultam na desativação automática.
• Tolere campos ausentes: campos opcionais podem não estar presentes dependendo do dispositivo e do momento do evento.

 

Formato legado (clientes antigos)

Se a sua integração foi criada antes da migração para o novo formato padrão, você continua recebendo os eventos de ponto de interesse (geofence_in e geofence_out) no formato antigo, com algumas diferenças:

Aspecto	Formato atual	Formato legado
Nomenclatura dos campos	camelCase (ex: eventId)	snake_case (ex: event_id)
Formato da data	ISO 8601 (ex: 2024-03-15T10:23:07Z)	yyyy-MM-dd HH:mm:ss
ID do veículo (vehicleId)	Presente	Ausente
Tipos de eventos disponíveis	Todos os eventos	Apenas pontos de interesse

O formato legado não será alterado — a compatibilidade é garantida indefinidamente para assinaturas existentes. Novas assinaturas utilizam o formato padrão.

 

Documentação técnica completa

Para detalhes técnicos completos, incluindo exemplos de payload, verificação de assinatura e guia de implementação, acesse a documentação oficial: docs.cobli.co/docs/webhooks