O que são Webhooks e como utilizar?
Entenda o que são webhooks, para que servem na gestão de frotas e como configurá-los no painel da Cobli.
Os webhooks permitem que a Cobli envie automaticamente informações sobre o que acontece na frota — ignição, velocidade, câmera, Locais de Interesse e muito mais — direto para um sistema que você já usa, como um ERP, TMS, planilha ou aplicativo próprio.
O que é um webhook
Imagine 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 que um webhook faz — de forma automática, sem ninguém precisar consultar nada.
Na prática: quando um evento ocorre na frota, a Cobli envia uma mensagem para uma URL do seu sistema. Ela chega em segundos e contém os dados do evento — qual veículo, quando aconteceu, onde estava, quem estava dirigindo.
Webhooks precisam de configuração técnica para funcionar. Se você não tem uma equipe técnica, este artigo ajuda a entender o que está disponível na Cobli para você conversar com o seu time de TI ou com um desenvolvedor.
Como é a mensagem enviada
A mensagem — chamada de payload — é estruturada e contém tipo de evento, horário, veículo e localização. 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
| 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 registro manual |
| Dashboard próprio com dados da frota | O sistema da empresa exibe posição e eventos dos veículos assim que chegam à Cobli, sem depender do painel |
| Alerta de segurança em sistema interno | O RH ou a 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 imediata.
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, por som dentro do veículo | Um sistema externo, na URL configurada |
| Para que serve | Avisar sobre eventos para você tomar uma ação | Avisar o motorista na hora | Integrar com sistemas da sua empresa |
| Configuração | Operação > Alertas | Configurações > Avisos sonoros | Integrações > Para desenvolvedores > 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 eventos organizados em grupos conforme os produtos e permissões da sua conta.
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 um local cadastrado |
| Saída de Local de Interesse | O veículo saiu de um local cadastrado |
| 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 |
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.
Rotas
Disponíveis apenas para frotas com o módulo de Serviços e Entregas ativado. Esses eventos aparecem na configuração do webhook somente para usuários com acesso à área de rotas no painel.
| Evento | O que indica |
|---|---|
| Rota iniciada | Uma rota planejada foi iniciada pelo motorista |
| Rota encerrada | Uma rota planejada foi encerrada |
Atividades
Disponíveis para frotas com o módulo de Serviços e Entregas ativado.
| Evento | O que indica |
|---|---|
| Atividade realizada | Uma atividade planejada foi concluída com sucesso |
| Atividade não realizada | Uma atividade planejada não foi concluída |
Os eventos de rotas e atividades só aparecem no formulário de webhook quando o módulo de Serviços e Entregas está ativo na conta e o usuário possui acesso à área de rotas. Se você não vê essas opções, verifique seu plano ou fale com o gerente de conta.
Quais informações chegam no payload
Cada evento contém um conjunto de dados sobre o que aconteceu. A tabela mostra o que pode estar presente, conforme o 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 Integrações > Para desenvolvedores > Webhooks no painel. A tela exibe todos os webhooks configurados na conta. Acima da lista, a faixa O que os webhooks resolvem traz quatro atalhos para a documentação técnica dos eventos (chegadas e entregas, riscos, ignição e posição, bateria e trava de ignição), e o botão Acessar documentação, no canto superior direito, leva à tela Documentação do Painel Cobli, de onde você chega ao portal docs.cobli.co.
Clique em Criar webhook, no canto superior direito. O painel de criação abre à direita, com 4 etapas.
Se o evento que você precisa não está na lista, role até o fim da tela: ao lado de Não encontrou o evento que esperava?, o botão Sugerir webhook abre a janela para enviar a sua sugestão ao time da Cobli.
Cadastrar informações
| Campo | O que preencher |
|---|---|
| Nome | Um nome para identificar o webhook na lista (ex: "Integração TMS", "Dashboard BI") |
| Payload URL | A URL do sistema que vai receber os eventos. O seu time técnico fornece 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 vieram mesmo da Cobli |
Você pode selecionar quantos eventos quiser — eles aparecem agrupados por categoria: Telemetria, Câmera, Microconfiguração (quando liberada para a frota) e, quando o módulo de Serviços e Entregas estiver ativo na conta e o usuário tiver acesso a rotas, também Rotas e Atividades. Também é possível ter vários webhooks com eventos diferentes: um para o TMS, outro para o BI.
Intervalos
Esta etapa controla com que frequência os eventos são enviados. É opcional: por padrão vem como "Sem intervalo", e cada evento é enviado imediatamente.
Para 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 ou minutos | Quando o evento ocorre 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).
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. O seu time técnico informa se algo precisa ser configurado aqui.
Teste
A etapa Teste do webhook só inicia a validação quando você clica em Testar e concluir (ao editar um webhook, o botão se chama Testar e salvar). A Cobli então envia uma requisição de teste para a URL configurada e uma barra de progresso acompanha as fases Iniciando requisição, Validando sucesso da requisição e Requisição realizada com sucesso. Se o sistema estiver pronto para receber, aparece a confirmação Webhook criado com sucesso. Se aparecer o aviso Erro no teste do webhook, confira com o time se a URL está correta e se o sistema está acessível.
Gerenciar webhooks existentes
Na listagem em Integrações > Para desenvolvedores > Webhooks você pode:
- Editar um webhook pelo ícone de lápis — abre o mesmo painel de criação com os dados preenchidos.
- Acompanhar o status na coluna "Status": Ativo, Com falhas (houve tentativas de envio sem sucesso) ou Inativo (o webhook para de enviar eventos, mas mantém a configuração). No painel de edição, Informações sobre falhas mostra quando as falhas começaram, quantas tentativas falharam e o motivo; um webhook inativo volta a enviar pelo botão Reativar, com confirmação.
- Pesquisar webhooks pelo nome no campo de busca.
- Atualizar a lista pelo botão com ícone de seta circular, ao lado do campo de busca — recarrega os webhooks sem sair da tela, útil para conferir uma mudança de status feita por outra pessoa.
- Excluir um webhook pelo botão Excluir webhook, no painel de edição. O painel Apagar webhook? pede confirmação e avisa que um webhook apagado não pode ser recuperado; clicar em Cancelar, no X ou fora da janela, ou pressionar Esc, mantém o webhook.
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 clique em Reativar no painel de edição do webhook.
Próximos passos
Webhooks precisam de um sistema preparado para receber as informações — uma API com um endereço (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 ajudá-los, compartilhe a documentação técnica de webhooks, 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: nossa equipe pode indicar parceiros e alternativas.
Perguntas frequentes
O que é a "Chave pública" e para que serve?
É uma chave de segurança que você e o seu time técnico definem juntos. Ela gera 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?
Sim. Você pode criar quantos webhooks precisar, cada um com eventos e URLs diferentes. Por exemplo: um 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?
Não. São canais diferentes, com destinatários diferentes: os alertas avisam você (gestor) por e-mail, app ou navegador, e 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?
Sim, por padrão o webhook recebe eventos de toda a frota. Não é possível filtrar por veículo ou grupo 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?
A Cobli tenta entregar o evento até 5 vezes, com intervalos crescentes: 2 segundos, 4 segundos, 8 segundos e 15 segundos nas duas últimas tentativas.
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 problema é afetada — outras assinaturas continuam funcionando.
Se os envios continuarem falhando por 7 dias consecutivos, a assinatura é desativada automaticamente e nenhum evento é entregue até você reativá-la no painel. 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?
Webhooks fazem parte das integrações da plataforma Cobli. Em caso de dúvida sobre a disponibilidade no seu contrato, entre em contato ou fale com o seu gerente de conta.
Veja também
- Criar, editar e desativar uma regra: os alertas que avisam você, e não um sistema externo.
- Avisos sonoros: o aviso que toca dentro do veículo.
- Locais de Interesse: as geofences usadas nos eventos de entrada e saída.
- API da Cobli: primeiros passos