![horizontal-white (1).png]](https://suporte.cobli.co/hs-fs/hubfs/horizontal-white%20(1).png?height=35&name=horizontal-white%20(1).png){kind=small}
Os webhooks permitem que a Cobli envie automaticamente informações sobre o que acontece na frota — ignição, velocidade, câmera, geofences e muito mais — direto para um sistema que você já usa, como um ERP, TMS, planilha ou aplicativo próprio. Este artigo explica o que é um webhook, para que serve e como configurar no painel.
Neste artigo cobrimos os seguintes tópicos:
- O que é um webhook
- Para que servem os webhooks na gestão de frota
- Diferença entre webhook, alerta e aviso sonoro
- Eventos disponíveis nos webhooks
- Quais informações chegam no payload
- Como configurar um webhook no painel
- Gerenciar webhooks existentes
- Próximos passos
- Perguntas frequentes
O que é um webhook
Imagine que você tem um funcionário de plantão, olhando a frota 24 horas por dia. Toda vez que um veículo liga a ignição, ultrapassa o limite de velocidade ou entra em um local de interesse, esse funcionário liga imediatamente para o seu sistema e passa a informação. Isso é o que um webhook faz — de forma automática, sem que ninguém precise consultar nada.
Na prática: quando um evento ocorre na frota, a Cobli envia uma mensagem automática para uma URL do seu sistema. Essa mensagem chega em segundos e contém os dados do evento — qual veículo, quando aconteceu, onde estava, quem estava dirigindo.
Se você não tem uma equipe técnica, não se preocupe: webhooks precisam de configuração técnica para funcionar. Este artigo vai te ajudar a entender o que está disponível na Cobli para que você possa conversar com o seu time de TI ou com um desenvolvedor de forma mais clara.
Como é a mensagem enviada
Quando um evento ocorre, a Cobli envia automaticamente uma mensagem estruturada — chamada de payload — para o sistema configurado. Ela contém os dados do evento: tipo de evento, horário, veículo, localização. Veja um exemplo simplificado:
{
"event_type": "ignition_on",
"event_time": "2024-03-15 08:32:10",
"event_data": {
"deviceId": "879797465464874",
"latitude": -23.5648,
"longitude": -46.6527
}
}
O formato completo de cada evento — com todos os campos e exemplos reais — está na documentação técnica.
Para que servem os webhooks na gestão de frota
Algumas situações em que frotas usam webhooks com a Cobli:
| Situação | Como o webhook ajuda |
|---|---|
| Integração com sistema de logística (TMS) | O TMS recebe automaticamente quando um veículo entra ou sai de um cliente, sem ninguém precisar registrar manualmente |
| Dashboard próprio com dados da frota | O sistema da empresa exibe posição e eventos dos veículos em tempo real, sem depender do painel Cobli |
| Alerta de segurança em sistema interno | O RH ou segurança recebe notificação imediata quando a câmera detecta fadiga ou uso de celular ao volante |
| Registro de produtividade | Cada ignição ligada e desligada é registrada automaticamente no sistema de horas ou de produtividade |
| Controle de combustível e manutenção | O sistema de manutenção recebe dados de ignição e odômetro para calcular quilometragem automaticamente |
Em resumo: webhooks são para quem quer que os dados da Cobli cheguem em outro sistema, de forma automática e em tempo real.
Diferença entre webhook, alerta e aviso sonoro
Os três têm funções parecidas, mas destinatários diferentes.
| Alerta | Aviso sonoro | Webhook | |
|---|---|---|---|
| Quem recebe | Você (gestor) — por e-mail, app ou navegador | O motorista — som dentro do veículo | Um sistema externo — URL configurada |
| Para que serve | Te avisar sobre eventos para tomar uma ação | Avisar o motorista na hora | Integrar com sistemas da sua empresa |
| Configuração | Operação > Alertas | Configurações > Avisos sonoros | Configurações > Webhooks |
| Precisa de técnico? | Não | Não | Sim |
Você pode ativar os três ao mesmo tempo para o mesmo evento — eles funcionam de forma independente.
Eventos disponíveis nos webhooks
A Cobli disponibiliza 21 tipos de evento, organizados em duas categorias.
Telemetria
Disponíveis para todos os veículos com dispositivo Cobli (OBD, instalado ou câmera).
| Evento | O que indica |
|---|---|
| Ignição ligada | O veículo foi ligado |
| Ignição desligada | O veículo foi desligado |
| Posição | Atualização periódica de localização com o veículo ligado |
| Posição com veículo desligado | Atualização periódica de localização com o veículo desligado |
| Entrada em local de interesse | O veículo entrou em uma geofence cadastrada |
| Saída de local de interesse | O veículo saiu de uma geofence cadastrada |
| Alerta de velocidade | O veículo ultrapassou o limite de velocidade configurado |
| Bateria externa baixa | A tensão da bateria do veículo caiu abaixo do limiar definido |
| Bateria externa desconectada | A bateria foi desconectada do dispositivo |
| Bateria externa reconectada | A bateria foi reconectada ao dispositivo |
| Frenagem brusca | Frenagem brusca detectada pelo acelerômetro |
| Aceleração brusca | Aceleração brusca detectada pelo acelerômetro |
| Curva brusca | Curva brusca detectada pelo acelerômetro |
Câmera
Disponíveis apenas para veículos com Cobli Cam instalada. A disponibilidade de cada evento depende do modelo da câmera.
| Evento | O que indica |
|---|---|
| Distância insegura | A câmera detectou que o veículo está muito próximo do carro da frente (ADAS) |
| Aviso de colisão frontal | A câmera detectou risco de colisão frontal (ADAS) |
| Direção distraída | A câmera detectou que o motorista está distraído (DMS) |
| Olhos fechados | A câmera detectou olhos fechados do motorista (DMS) |
| Uso de celular | A câmera detectou uso de celular ao volante (DMS) |
| Fumando ao volante | A câmera detectou cigarro (DMS) |
| Bocejo | A câmera detectou bocejo do motorista (DMS) |
| Botão do motorista | O motorista acionou o botão de emergência ou notificação do dispositivo |
Importante: os eventos de câmera exigem Cobli Cam instalada no veículo. Se o seu contrato não inclui câmeras, esses eventos não estarão disponíveis.
Quais informações chegam no payload
Cada evento enviado pelo webhook contém um conjunto de dados sobre o que aconteceu. A tabela abaixo mostra quais informações podem estar presentes, dependendo do tipo de evento.
Legenda: ✓ sempre presente · ◦ pode estar presente · — não se aplica
| Informação | Ignição e posição | Geofences | Velocidade — início | Velocidade — fim | Bateria | Câmera |
|---|---|---|---|---|---|---|
| ID do evento | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Tipo do evento | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Data e hora | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| ID do dispositivo | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| ID do veículo | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| ID da frota | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Placa do veículo | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| ID do motorista | ◦ | ◦ | ◦ | ◦ | — | ◦ |
| Cobli ID do dispositivo | ◦ | ◦ | ◦ | ◦ | ◦ | ◦ |
| Latitude | ◦ | ◦ | ◦ | ◦ | ◦ | ◦ |
| Longitude | ◦ | ◦ | ◦ | ◦ | ◦ | ◦ |
| Direção do veículo | ◦ | — | — | — | ◦ | ◦ |
| Estado da ignição | ◦ | — | — | — | ◦ | ◦ |
| Velocidade (km/h) | ◦ | ◦ | ◦ | ◦ | ◦ | ◦ |
| Odômetro (km) | ◦ | ◦ | — | — | ◦ | ◦ |
| Tensão da bateria | ◦ | — | ◦ | ◦ | ◦ | ◦ |
| Tipo de conexão | ◦ | — | — | — | ◦ | ◦ |
| Nível de combustível ¹ | ◦ | — | — | — | — | — |
| RPM do motor ¹ | ◦ | — | — | — | — | — |
| Satélites GPS | ◦ | — | — | — | — | ◦ |
| Precisão do GPS | ◦ | — | ◦ | ◦ | — | ◦ |
| Nome do local de interesse | — | ◦ | — | — | — | — |
| Endereço do local de interesse | — | ◦ | — | — | — | — |
| Limite de velocidade configurado | — | — | ✓ | ✓ | — | — |
| Severidade do alerta | — | — | ✓ | ✓ | — | — |
| Horário de início do alerta | — | — | — | ✓ | — | — |
| Duração acima do limite | — | — | — | ✓ | — | — |
| Threshold de bateria baixa | — | — | — | — | ✓ | — |
| Sistema elétrico (12V / 24V) | — | — | — | — | ◦ | — |
¹ Disponível apenas em veículos com barramento CAN conectado (dados lidos diretamente pelo sistema elétrico do veículo).
O campo "ID do motorista" só aparece quando há um motorista identificado e associado ao veículo no momento do evento. Para campos opcionais, a ausência no payload significa que o dado não estava disponível naquele momento — projete a integração para tolerar campos ausentes.
Para o formato técnico completo — nomes dos campos em inglês, tipos de dado e exemplos de payload — consulte a documentação técnica.
Como configurar um webhook no painel
Acesse Configurações > Webhooks no painel Cobli. A tela exibe todos os webhooks configurados na conta.
Clique em + Criar webhook. O painel de criação abre à direita com 4 etapas.
Etapa 1 — Cadastrar informações
| Campo | O que preencher |
|---|---|
| Nome | Um nome para identificar este webhook na lista (ex: "Integração TMS", "Dashboard BI") |
| Payload URL | A URL do sistema que vai receber os eventos. Seu time técnico precisa fornecer essa URL |
| Seleção de alertas | Os tipos de evento que este webhook deve monitorar. Clique em "Selecionar alertas" para escolher |
| Chave pública | Uma chave de segurança definida por você e pelo time técnico. Ela valida que os eventos recebidos vieram mesmo da Cobli |
Você pode selecionar quantos eventos quiser. Eles aparecem agrupados em "Telemetria" e "Câmera". É possível ter múltiplos webhooks com eventos diferentes — um para o TMS, outro para o BI, por exemplo.
Etapa 2 — Intervalos
Esta etapa controla com que frequência os eventos são enviados para o seu sistema. É opcional e por padrão vem como "Sem intervalo" — cada evento é enviado imediatamente.
Se você quiser controlar a frequência, clique em Personalizar no evento desejado e escolha o modo:
| Modo | Como funciona | Quando usar |
|---|---|---|
| Sem intervalo | Cada ocorrência gera um envio imediato | Quando você precisa de cada evento individualmente (ex: ignição ligada) |
| Intervalo mínimo | Envia no máximo 1 notificação a cada X segundos/minutos | Quando o evento pode ocorrer com frequência alta e você não quer sobrecarregar o sistema (ex: posição GPS) |
| Acúmulo mínimo | Só envia se o evento ocorrer N ou mais vezes no intervalo | Quando um evento isolado não é relevante, mas a repetição é (ex: 3 frenagens bruscas em 1 minuto) |
Para Intervalo mínimo e Acúmulo mínimo, defina o tempo em segundos ou use os atalhos: 10s, 30s, 5 min, 20 min, 1h.
Para Acúmulo mínimo, defina também o número mínimo de ocorrências (mínimo 2).
Etapa 3 — Cabeçalhos
Opcional. Permite adicionar headers HTTP customizados à requisição — informações extras que o seu sistema pode usar para identificar ou autenticar a origem da mensagem. Seu time técnico vai informar se precisa configurar algo aqui.
Etapa 4 — Teste
Clique em Testar e Concluir para que a Cobli envie uma requisição de teste para a URL configurada. Se o sistema do seu time técnico estiver pronto para receber, você verá uma confirmação de sucesso. Se aparecer um erro, confira com o time se a URL está correta e se o sistema está acessível.
Gerenciar webhooks existentes
Na tela de listagem em Configurações > Webhooks, você pode:
- Editar um webhook clicando no ícone de lápis — abre o mesmo painel de criação com os dados preenchidos
- Ativar ou desativar clicando no botão de status na coluna "Status" — um webhook inativo para de enviar eventos, mas mantém toda a configuração
- Pesquisar webhooks pelo nome usando o campo de busca
Se um webhook falhar repetidamente por 7 dias seguidos, a Cobli o desativa automaticamente. Para reativar, peça ao time técnico que corrija a URL de destino e então reative o webhook pelo painel.
Próximos passos
Webhooks precisam de um sistema preparado para receber as informações. Esse sistema precisa ter uma API — um endereço técnico (chamado de endpoint) que fica aguardando as mensagens da Cobli e sabe o que fazer com elas. Criar e manter essa API é responsabilidade do time técnico.
Para colocar em funcionamento, você vai precisar do apoio do seu time de TI ou de um desenvolvedor.
Para ajudá-los, compartilhe este link com a documentação técnica completa dos webhooks da Cobli, que inclui o formato dos dados, exemplos de payload e instruções de segurança:
Se você não tem um time técnico interno e precisa de uma integração, entre em contato com o suporte Cobli — nossa equipe pode indicar parceiros e alternativas.
Perguntas frequentes
O que é a "Chave pública" e para que serve?
R: É uma chave de segurança que você e seu time técnico definem juntos. Ela é usada para gerar uma assinatura em cada mensagem enviada pela Cobli, garantindo que o dado recebido veio realmente da Cobli e não de outra fonte. Pense nela como uma senha compartilhada entre a Cobli e o seu sistema.
Posso ter mais de um webhook na minha conta?
R: Sim. Você pode criar quantos webhooks precisar, cada um com eventos e URLs diferentes. Por exemplo: um webhook enviando dados de ignição para o seu TMS e outro enviando eventos de câmera para o sistema de segurança.
Webhook substitui os alertas?
R: Não. São canais diferentes com destinatários diferentes. Os alertas avisam você (gestor) por e-mail, app ou navegador. Os webhooks enviam dados para um sistema externo. Você pode usar os dois ao mesmo tempo para o mesmo evento.
O webhook funciona para todos os veículos da frota?
R: Sim, por padrão o webhook recebe eventos de toda a frota. Não é possível filtrar por veículo ou grupo diretamente na configuração do webhook — se precisar filtrar, isso deve ser feito no sistema receptor.
O que acontece se o meu sistema ficar fora do ar?
R: 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
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.
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.
Preciso de um plano específico para usar webhooks?
R: Webhooks fazem parte das integrações da plataforma Cobli. Em caso de dúvida sobre disponibilidade no seu contrato, entre em contato com o suporte ou com o seu gerente de conta.