Webhooks

Um webhook envia, automaticamente, os eventos da frota para um endereço do sistema da sua empresa assim que eles acontecem, como uma ignição ligada ou a entrada em um Local de Interesse. Na tela Webhooks, você cria esses envios, acompanha se estão funcionando e reativa os que foram desativados por falha. A configuração costuma ser feita junto com o time de tecnologia, que fornece o endereço que vai receber os eventos.

Pré-requisitos

• Ter a permissão de Integrações no seu perfil de usuário
• Ter, do time de tecnologia, a URL (com https) que vai receber os eventos e a chave combinada para validar as mensagens
• Saber quais eventos o sistema de destino precisa receber

Passo a passo

O que a tela mostra

• Acessar documentação: botão no canto superior direito que leva à tela Documentação do Painel Cobli.
• O que os webhooks resolvem: quatro cartões com situações de uso, cada um com um link que abre, em outra aba, os eventos correspondentes na referência da API.
  • Avisar quem está esperando: confirme chegadas e entregas ao cliente assim que o veículo entra no local ou conclui a parada (Eventos de local e de rota).
  • Tratar o desvio no mesmo minuto: excesso de velocidade, condução brusca e SOS chegam enquanto o veículo ainda está na rua (Eventos de risco).
  • Manter seu sistema espelhado: ignição, posição e associação de motorista atualizam o seu sistema sem consultas repetidas (Eventos de ignição e posição).
  • Proteger o ativo parado: bateria desconectada, tensão baixa e trava de ignição viram chamado automático na operação (Eventos de bateria e trava).
• Lista de webhooks: colunas Nome, URL, Chave pública, Eventos cadastrados, Status e Ações, com busca pelo nome e um botão para atualizar a lista.
• Sugerir webhook: no fim da tela, ao lado de Não encontrou o evento que esperava?, abre uma janela em duas etapas, Webhook (qual evento você gostaria de sugerir) e Objetivo (o que você quer resolver com ele).

Campos do webhook

• Nome (obrigatório): indique o sistema de destino ou o processo atendido. Aceita até 90 caracteres.
• Payload URL (obrigatório): o endereço que recebe os eventos. Precisa ser uma URL segura, com protocolo https.
• Chave pública (obrigatória): apesar do nome, é um segredo compartilhado entre a Cobli e o sistema de destino. Ela gera a assinatura enviada no cabeçalho, que permite ao sistema de destino confirmar que a mensagem veio da Cobli. Não divulgue esse valor: quem o tiver consegue forjar mensagens que parecem vir da Cobli.
• Seleção de alertas (obrigatório): escolha pelo menos um evento. Os eventos aparecem em seções: Telemetria e Câmera; Microconfiguração, quando liberada para a frota; e Rotas e Atividades, quando a frota usa Serviços e entregas e o seu usuário tem acesso a rotas.

Intervalos de envio

Na etapa Intervalos, cada tipo de evento selecionado mostra o selo Padrão ou Personalizado. Clique em Personalizar para mudar a frequência e escolha o Modo:

• Intervalo mínimo: envia no máximo uma notificação a cada intervalo definido. O tempo mínimo é de 10 segundos.
• Acúmulo mínimo: envia somente quando houver um número mínimo de ocorrências dentro do intervalo. A quantidade mínima é 2.

Para voltar ao comportamento original, clique em Restaurar padrão.

Status e reativação

A coluna Status mostra a situação de cada webhook:

• Ativo (verde): os envios estão funcionando.
• Com falhas (amarelo): o webhook continua ativo, mas houve tentativas de envio sem sucesso.
• Inativo (vermelho): o webhook foi desativado e não envia mais eventos, mas mantém a configuração.

Para entender o problema, abra o webhook pelo botão Editar, na coluna Ações. Em Informações sobre falhas aparecem o Início das falhas, as Tentativas com falha, o Motivo e, se for o caso, a data em Desativado em. Depois que o time de tecnologia corrigir o sistema de destino, clique em Reativar, no rodapé do painel de edição, e confirme na janela Reativar webhook.

Editar e excluir

No painel de edição, as mesmas etapas da criação ficam disponíveis. Para salvar uma alteração, avance até a última etapa e clique em Testar e salvar: o teste roda de novo antes de gravar a mudança. Para excluir, clique em Excluir webhook e confirme; um webhook excluído não pode ser recuperado.

Erros comuns no teste

Dicas

Veja também

• O que são Webhooks e como utilizar: eventos disponíveis e dados de cada envio.
• Documentação: guias e referência para o time de tecnologia.
• Alertas: avisos para o gestor, por e-mail, aplicativo ou navegador.