Kafka API

Alongside our REST API, Hiboo also exposes a Kafka API for customers who need equipment data delivered as a continuous, low-latency stream rather than fetched on demand.

When to use the Kafka API

The REST API is the primary way to integrate with Hiboo and covers most use cases: fleet browsing, history, snapshots, and reporting. The Kafka API complements it when you need:

• Real-time data: events are pushed as soon as Hiboo processes them, with no polling delay.

• Push-based integrations: a natural fit for streaming pipelines, data lakes, and event-driven architectures.

• High-throughput ingestion: built to handle large fleets without the overhead of pagination or rate management.

Not sure which one you need? Start with the REST API. The Kafka API is an add-on for streaming use cases and requires a dedicated onboarding.

Authentication with mTLS

The Kafka API is secured with mutual TLS (mTLS). Unlike the REST API, it uses no x-access-token header: the client proves its identity with a certificate issued by Hiboo.

When your Kafka access is provisioned, Hiboo provides:

• A client certificate (.crt)

• A private key (.key)

• The CA certificate used to verify the broker (ca.crt)

• The list of bootstrap brokers and the topic you are authorized to consume

Treat the private key like any other secret: store it securely, never commit it to source control, and request a new one if you suspect it has been exposed.

Topic & message format

Each customer is provisioned with a single dedicated topic carrying all of their time-series data. There is no need to subscribe to multiple topics: every dataKind (positions, fault codes, fuel, operating hours, and so on) flows through the same stream.

Each message is a JSON object. The dataKind field tells you which type of data you are reading.

Example — position message:

{
  "assetId": 123456,
  "datetime": "2026-04-22T14:49:07.000Z",
  "dataKind": "position",
  "dataSourceCode": "ocean",
  "latitude": 48.85837,
  "longitude": 2.294481,
  "postalAddress": "5 Av. Anatole France, 75007 Paris, France",
  "timezone": "Europe/Paris",
  "altitude": null,
  "speed": 26,
  "heading": null,
  "precision": null,
  "origin": null
}

Example — battery voltage message:

{
  "assetId": 100,
  "datetime": "2024-09-14T13:08:35.000Z",
  "dataKind": "battery_voltage",
  "dataSourceCode": "volvotrucks_connect",
  "volts": 12.5
}

Example — fault codes message:

{
  "assetId": 100,
  "datetime": "2024-09-14T13:08:35.000Z",
  "dataKind": "fault_codes",
  "dataSourceCode": "volvotrucks_connect",
  "level": 2,
  "label": "D1DIG.1",
  "description": "GPMECU - General Purpose Machine Electronic Control Unit 1",
  "extraInfo": "{\"more\": "\data\"}"
}

Example — sensor boolean message:

{
  "assetId": 100,
  "datetime": "2024-09-14T13:08:35.000Z",
  "dataKind": "sensor_boolean",
  "dataSourceCode": "samsara",
  "type": "checkEngineLights.stopIsOn",
  "status": false
}

Example — cumulative distance message:

{
  "assetId": 100,
  "datetime": "2024-09-14T13:08:35.000Z",
  "dataKind": "cumulative_distance",
  "dataSourceCode": "volvotrucks_connect",
  "kilometers": 80853.3
}

Example — cumulative usage hours message:

{
  "assetId": 100,
  "datetime": "2024-09-14T13:08:35.000Z",
  "dataKind": "cumulative_usage_hours",
  "dataSourceCode": "volvotrucks_connect",
  "hours": 1802.4
}

Example — engine condition message:

{
  "assetId": 100,
  "datetime": "2024-09-14T13:08:35.000Z",
  "dataKind": "engine_condition",
  "dataSourceCode": "volvotrucks_connect",
  "running": "on",
  "engineNumber": "HC17007"
}

Example — sensor temperature message:

{
  "assetId": 100,
  "datetime": "2024-09-14T13:08:35.000Z",
  "dataKind": "temperature",
  "dataSourceCode": "samsara",
  "type": "front - ambientTemperature",
  "celsius": 21.96,
}

Key fields to know:

• assetId: the Hiboo equipment identifier, matching the id returned by the REST fleet endpoints.

• datetime: the UTC timestamp of the event (ISO 8601). Daily data kinds use date instead.

• dataKind: the type of data carried by the message. Use it to route each message to the right handler on your side.

• dataSourceCode: the source provider of the message.

Getting access

The Kafka API is not self-service. To request access:

1. Contact us at [e-mail] with your use case and expected volume.

2. Our team provisions your certificates and shares the broker endpoints.

3. Connect from any Kafka-compatible client (Java, Python confluent-kafka, and others) configured for mTLS.