activity_completed — Parada concluída

Disparado quando uma parada é concluída, total ou parcialmente.

activity.outcome distingue os dois casos — e PARTIALLY_COMPLETED é conclusão,
não falha
: falha é o tipo activity_failed, que pode ser assinado à parte.

activity.windowCompliance entrega o cumprimento da janela já resolvido contra
activity.timeWindows: ON_TIME quando a conclusão cai dentro de qualquer janela,
EARLY só quando precede todas, LATE no resto — inclusive no vão entre duas janelas.

Assine o grupo activities — plural, literalmente "activities" em event_types.
Grupo de composição fechada: entrega exatamente activity_completed e
activity_failed.

O bloco route está presente, salvo numa parada que não pertence a nenhuma rota.

deviceId e vehicleId podem não vir. O contrato os declara opcionais e eles
são omitidos do eventData quando não há dispositivo ou veículo associado. O
envelope interno ainda carrega deviceId como string vazia — é uma restrição do
nosso armazenamento, não um identificador válido. Use o eventData.

Trate o webhook como sinal, não como fonte da verdade. O evento é publicado
dentro da transação do domínio, então numa falha rara você pode receber um evento
cujo estado não persistiu. Em caso de divergência, reconcilie por
GET /public/v2/routes.

eventData é aninhado. Um handler que espera o formato plano dos demais tipos
não encontra nenhum campo — eles vivem em eventData.route e eventData.activity.


Entregue pela assinatura do tipo activities.
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 activity_completed.

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.

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.

date-time
required

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

string
enum
required

Tipo do evento.

Allowed:
eventData
object
required

Único eventData aninhado do catálogo: os dados da rota vão em route e os da parada em activity. Um handler que espera o formato plano não encontra nenhum campo.

deviceId, vehicleId e licensePlate são opcionais aqui — uma rota encerrada por inatividade sem nunca ter iniciado pode não ter dispositivo nem veículo associados. Os dois blocos também podem estar ausentes.

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.

LoadingLoading…