geofence_in — Veículo entrou em um ponto de interesse

webhook

geofence_in

Disparado na entrada de um ponto de interesse cadastrado na frota.

O ponto cruzado vem em geofenceId, name e address. Veículos sem posição
válida no instante do cruzamento não geram o evento.

Formato legado. Assinaturas criadas antes da migração recebem geofence_in
e geofence_out em snake_case — event_id, event_type, event_time,
event_data —, com event_time em "yyyy-MM-dd HH:mm:ss" (UTC) e sem
vehicleId. Se é o seu caso, o schema abaixo não descreve o corpo que você
recebe. Esses são os dois únicos tipos afetados; para migrar para o formato
canônico, abra ticket em #help-tech-account-mgm.

Assine o tipo geofence_in para receber este evento.
A Cobli envia este evento como POST application/json para a URL cadastrada na
assinatura, assinado em X-Cobli-Signature. Responda 2xx em até 5 segundos e
deduplique por eventId.

Payload

Envelope do evento geofence_in.

Envelope comum a todos os eventos de webhook da Cobli. O corpo da requisição POST é sempre este objeto — o que varia entre os tipos é o conteúdo de eventData.

eventId

uuid

required

Identificador determinístico do evento, derivado de fleetId + signatureId + deviceId + eventType + eventTime. Nos eventos de rota e parada o identificador do recurso (routeId ou activityId) também entra na derivação, para que dois recursos encerrados no mesmo milissegundo não colidam.

O mesmo evento sempre produz o mesmo eventId — em retentativas, em retransmissões e na recuperação via GET /public/v2/events. Use como chave de idempotência.

eventTime

date-time

required

Momento em que o evento ocorreu no dispositivo, em ISO 8601 UTC.

eventType

string

enum

required

Tipo do evento.

Allowed:

eventData

object

required

Campos de telemetria presentes em todos os eventos de escopo de dispositivo.

Ausente e null não são a mesma coisa, e a regra muda por família de evento. Em geofence_in/geofence_out, nos 11 de câmera, nos dois de velocidade e nos quatro de rota e parada, o campo sem dado é omitido. Em ignition_on, ignition_off, position, position_sleep e nos três battery_external_*, o campo sem dado vem presente com valor null — exceto cobliId, speedInKmh, licensePlate e networkSignal, que são omitidos em qualquer tipo. fleetId é sempre preenchido na entrega, e por isso segue em required. Projete o integrador para tolerar as duas formas em todo campo opcional.

Responses

200

Evento aceito. Responda 2xx em até 5 segundos — enfileire e processe de forma assíncrona se o seu processamento for demorado. Nenhuma retentativa é feita.

400

Evento rejeitado de forma permanente — use para assinatura HMAC inválida ou payload malformado. A Cobli trata 4xx como falha definitiva e não retenta, com duas exceções: 429 (ver abaixo) e 401 em assinaturas com Bearer auth habilitado, em que a Cobli renova o token e retenta. Não devolva 4xx para um eventType que você não espera: ignore-o e responda 2xx.

500

Falha temporária no seu lado. A Cobli faz até 5 tentativas no total, com backoff exponencial entre elas — 2 s → 4 s → 8 s → 15 s —, jitter de ±20 % e teto de 15 s por intervalo. O mesmo vale para timeout: sem resposta em 5 segundos.

Loading…

429Limite de vazão atingido no seu lado. A Cobli retenta respeitando o header Retry-After quando presente, limitado a 15 segundos — valores maiores são truncados. Sem o header, ou com ele no formato HTTP-date, aplica o backoff exponencial padrão.