Webhooks

O que é webhook?

Webhook é uma tecnologia que permite que a Cobli envie uma requisição HTTP POST para a sua aplicação sempre que um evento relevante ocorrer na frota — sem que você precise ficar consultando nossa API. Use webhooks para:

• Disparar alertas em tempo real (câmera, velocidade, bateria baixa)
• Integrar rastreamento de frota com sistemas internos
• Automatizar fluxos a partir de eventos de ignição ou ponto de interesse

Eventos disponíveis

Consulte os eventos disponíveis e seus formatos em: https://docs.cobli.co/reference/webhookgeofencein

Primeiros passos

1. Crie um endpoint HTTP que aceite POST com Content-Type: application/json.

   • Responda 2xx em até 5 segundos. Processe de forma assíncrona se necessário.
   • Valide o header X-Cobli-Signature antes de processar — ver Verificação de assinatura.

2. Cadastre a assinatura no painel Cobli em Configurações → Webhooks.

   • Informe a URL, a chave secreta e os tipos de evento desejados.

3. Valide a integração — gere um evento de teste (ex: ligue a ignição de um veículo)
   e confirme que seu endpoint recebe o payload esperado.

Verificação de assinatura

Cada requisição inclui o header X-Cobli-Signature com a assinatura HMAC-SHA256 do corpo (eventData serializado), codificada em hexadecimal. Use a secretKey configurada na assinatura para verificar a autenticidade:

import hmac, hashlib

def verificar(secret: str, body: bytes, assinatura: str) -> bool:
    esperado = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperado, assinatura)

Rejeite requisições sem X-Cobli-Signature válido com status 400. Nunca processe um payload cuja assinatura não pôde ser verificada.

Retentativas e idempotência

Comportamento por código de resposta

Política de backoff exponencial

Progressão típica (sem jitter): 2 s → 4 s → 8 s → 15 s → 15 s.

Pausa automática por falha em sequência

Após 5 falhas consecutivas para a mesma URL de destino, as entregas para aquela URL são pausadas automaticamente por 60 segundos. Após o intervalo, as entregas são retomadas sem intervenção necessária.

Essa pausa afeta apenas a URL com falhas — outras assinaturas com URLs diferentes não são impactadas.

Use eventId como chave de idempotência. Em caso de retentativa, o mesmo evento pode ser entregue mais de uma vez. Armazene os IDs já processados para evitar efeitos duplicados.

Desativação automática por falha persistente

Se as entregas para uma assinatura falharem continuamente por 7 dias, a assinatura é desativada automaticamente. Nesse estado:

• O campo active da assinatura passa a false
• failure_started_at registra o início da janela de falha
• failure_reason descreve o motivo (ex: "HTTP 503", "TIMEOUT")
• deactivated_at registra o momento da desativação
• Nenhum novo evento é entregue até que a assinatura seja reativada manualmente

Para reativar, corrija o endpoint e reabilite a assinatura no painel Cobli. Eventos gerados durante o período de inatividade não são retransmitidos.

Boas práticas

• Responda rápido, processe depois. Seu endpoint deve responder 2xx em até 5 s.
  Enfileire o evento e processe em background para evitar timeout.

• Use eventId como chave de idempotência. O mesmo evento pode ser entregue mais
  de uma vez em caso de retentativa. Armazene os IDs já processados para evitar duplicidade.

• Valide sempre a assinatura antes de processar o payload — rejeite requests
  sem X-Cobli-Signature válido com 400.

• Não retente erros 4xx no seu lado. A Cobli interpreta 4xx como falha
  permanente e não fará novas tentativas. Corrija sua integração e aguarde novos eventos.

• Filtre por eventType no início do handler para ignorar tipos não esperados
  sem retornar erro — isso evita 4xx desnecessários.

• Monitore failure_started_at. Esse campo indica que a Cobli está enfrentando
  falhas de entrega para a sua assinatura. Atue antes dos 7 dias para evitar desativação automática.

• Tolere campos ausentes. Campos opcionais podem estar ausentes ou nulos dependendo
  do modelo do dispositivo e da disponibilidade do dado no momento do evento. Não assuma presença.

• Nos eventos de rota e parada, leia o eventData aninhado. Um handler que espera eventData plano não encontra os campos: eles vivem em eventData.route e eventData.activity. Os dois blocos podem estar ausentes, e deviceId/vehicleId também.

Formato legado (retrocompatível)

Assinaturas criadas antes da migração para o formato padrão continuam recebendo o payload no formato legado. Esse formato não sofrerá mudanças — a compatibilidade é garantida indefinidamente para assinaturas existentes.

O formato legado é aplicado apenas aos eventos geofence_in e geofence_out.

{
  "event_id"  : "7decdf99-283d-4c70-9b95-a3b3f896e9b9",
  "event_type": "geofence_in",
  "event_time": "2022-09-08 15:47:46",
  "event_data": {
    "fleetId"   : "cf3f1990-2ce3-4ed9-85c5-9a528295ecfe",
    "deviceId"  : "879797465464874",
    "latitude"  : -23.764235,
    "longitude" : -46.595110,
    "geofenceId": "59e88bca-d3b9-4980-95a9-421fe2ffb275",
    "name"      : "MEU LOCAL DE INTERESSE",
    "address"   : "Rua Lourenço Marques, 297, São Paulo - SP, 04547-100"
  }
}

Diferenças em relação ao formato padrão: