Webhooks overview

Telemax webhooks push alert event payloads to a URL you control the moment an alert fires. No polling required.

How it works

Create a webhook via POST /v2/api/webhooks. You receive a plaintext HMAC secret in the response — save it securely, it is returned only once.
Link one or more alert configurations to the webhook (via alertIds on creation, or later via POST /v2/api/webhooks/{id}/link-alert). Alternatively, set isGlobal: true to receive alerts from your company and all its sub-companies (see Global vs alert-scoped webhooks).
When a linked alert fires, Telemax sends an HTTP POST to your URL with a signed JSON payload.

Webhook deliveries only start once Telemax has enabled webhook alerts for your company. Until then, creating a webhook and linking alerts both succeed, but nothing is sent. Contact Telemax support to have it enabled. For an alert-scoped webhook, the setting is checked on the company that owns the linked alert configuration; for a global webhook, on the company that owns the webhook.

Payload shape

Every webhook payload key on this page is PascalCase, unlike REST API responses, which are camelCase. Match key names exactly.

{
  "AlertType": "ExceedMaximumSpeed",
  "VehicleId": 51207,
  "VehicleName": "Delivery Van 07",
  "Position": {
    "Lat": -33.8688,
    "Lng": 151.2093
  },
  "Direction": 270,
  "Timestamp": "2026-04-28T06:14:22Z",
  "Address": {
    "Country": "Australia",
    "CountryCode": "AUS",
    "State": "New South Wales",
    "StateCode": "NSW",
    "City": "Sydney",
    "Suburb": "Sydney",
    "Street": "George Street",
    "Building": "42",
    "PostalCode": "2000"
  },
  "Data": {
    "Speed": 127.4,
    "MaxSpeed": 110
  }
}

Field	Type	Description
`AlertType`	string	Event type, e.g. `"ExceedMaximumSpeed"`. Every value is listed under Supported alert types
`VehicleId`	integer	Internal Telemax vehicle ID, the same value as `vehicleId` in alert records. It can differ from `deviceId` in position data, from `{id}` in `/v2/api/vehicles/{id}`, and from `units[].vehicleId` in `GET /v2/api/companies/{id}/alerts`
`VehicleName`	string	Vehicle display name
`Position.Lat` / `Position.Lng`	number	GPS coordinates at trigger
`Direction`	integer	Heading in degrees (0–359)
`Timestamp`	datetime	UTC trigger time, ISO 8601 ending in `Z`; may include fractional seconds
`Address`	object \| null	Reverse-geocoded location, always with 9 keys: `Country`, `CountryCode` (ISO 3166-1 alpha-3), `State`, `StateCode`, `City`, `Suburb`, `Street`, `Building` (house number), `PostalCode`. Every key except `Country` and `CountryCode` can be `null`
`Data`	object \| null	Type-specific payload (see below)

Type-specific `Data` payloads

The Data field carries additional context depending on AlertType: Geofence ("Geofence")

{ "GeofenceName": "Depot Zone", "IsExit": true }

Ignition ("Ignition")

{ "IsStarted": true }

Low battery ("LowBattery")

{ "Voltage": 11.8, "Threshold": 12 }

Maximum speed ("ExceedMaximumSpeed")

{ "Speed": 127.4, "MaxSpeed": 110 }

Speed and MaxSpeed are in km/h, and Voltage and Threshold in volts. All four are decimal numbers; whole values are sent without a decimal point. For every other alert type, Data is null.

Supported alert types

The integer type ID is the one the 422 error message quotes. GET /v2/api/companies/{id}/alert-records returns only some of these types as alertType; see its Alert types. GET /v2/api/companies/{id}/alerts returns a name instead, so the tables list both.

Alert-scoped webhooks

Alert configurations of these types can be linked to a webhook. A maximum of 50 alert configurations can be linked to a single webhook.

Type ID	`alertType` in `GET …/alerts`	`AlertType` in the payload	`Data`
1	Device Disconnected	`DeviceDisconnected`	`null`
2	Device Reconnected	`DeviceReconnected`	`null`
5	Geofence	`Geofence`	`GeofenceName`, `IsExit`
8	Ignition	`Ignition`	`IsStarted`
9	Low Battery	`LowBattery`	`Voltage`, `Threshold`
10	Exceed Maximum Speed	`ExceedMaximumSpeed`	`Speed`, `MaxSpeed`

Linking a type that is not in this table returns 422. The exception is Exceed Engine Temperature (17): the link is accepted, but nothing is delivered for it.

Global webhooks

A global webhook receives the six types above, with the same payloads, plus these types with Data: null:

Type ID	`alertType` in `GET …/alerts`	`AlertType` in the payload
3	Engine Fault	`Engine Code`
4	Fatigue	`Fatigue`
6	Geofence Speed	`Geofence Speed`
7	Idle	`Idle`
11	Mileage	`Mileage`
12	Above Speed Limit	`Speed Limit`
13	Doors Unlocked	`Door Unlocked`
14	Tire Pressure	`Low Tire Pressure`
19	Road Surface	`Road Surface`

Some of these values contain spaces. For types 3, 12, 13 and 14 the payload value differs from the name GET …/alerts returns. Charging (15), Exceed RPM (16), Exceed Engine Temperature (17) and Driving after dark (20) are not delivered to webhooks.

Request headers

Every delivery includes two headers:

Header	Description
X-Telemax-Signature	`sha256=<hex>` — HMAC-SHA256 signature of the raw request body
X-Telemax-Delivery	UUID identifying this delivery attempt. Each retry gets a new UUID.

Verifying the signature

Compute HMAC-SHA256(secret, rawBody) and compare the hex digest to the value after sha256= in X-Telemax-Signature. Use the secret exactly as it was returned, as UTF-8 text; do not hex-decode it. Always compare using a constant-time function to prevent timing attacks.

import hmac, hashlib

def verify(secret: str, body: bytes, header: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    received = header.removeprefix("sha256=")
    return hmac.compare_digest(expected, received)

import { createHmac, timingSafeEqual } from "crypto";

function verify(secret, body, header) {
  const expected = Buffer.from(createHmac("sha256", secret).update(body).digest("hex"));
  const received = Buffer.from(String(header ?? "").replace("sha256=", ""));
  return expected.length === received.length && timingSafeEqual(expected, received);
}

Global vs alert-scoped webhooks

	Global (`isGlobal: true`)	Alert-scoped
Fires for	Alerts configured in the webhook’s company and all its sub-companies (see Supported alert types)	Only the linked alert configurations
`alertIds` required	No	Yes (at least one)
Mixed payload types	Yes — `Data` shape varies per alert	Predictable if only one type is linked

When multiple alert types are linked to one webhook, Data will have different structures per delivery. The AlertType field tells you which shape to expect. Consider using one webhook per alert type for simpler integration.

Delivery retries

Telemax normally makes up to 3 attempts per event, within about 22 seconds. An attempt fails on a non-2xx response, a connection error, or no response within 5 seconds. The second attempt follows 2 seconds after the first fails, and the third 5 seconds after the second. After the third failure the event is dropped. If your host name does not resolve, or resolves only to a private or reserved address, when the event is sent, the event is dropped without an attempt. Respond with a 2xx within 5 seconds, and do any heavy processing asynchronously. Register the final URL of your endpoint and do not rely on redirects. A 300, 301, 302 or 303 is re-sent as a GET without the body, so the event can count as delivered while your endpoint never receives it. X-Telemax-Delivery changes on every attempt, so it cannot be used to detect a retry. Retries of an event carry a byte-identical body. Rarely, for example after a Telemax restart, an event is delivered again later as a separate event with the same body. Several alert configurations of the same type that cover one vehicle and deliver to the same webhook each produce their own delivery, and nothing in the body identifies the configuration: when two of them fire on the same vehicle message with the same Data, for example because they have the same settings, their bodies are identical. To de-duplicate, use a hash of the raw body, not a short time window. A byte-identical body means the same vehicle, alert type, time and data.

Managing webhooks

Create

POST /v2/api/webhooks

List

GET /v2/api/webhooks

Get

GET /v2/api/webhooks/{id}

Update

PUT /v2/api/webhooks/{id}

Delete

DELETE /v2/api/webhooks/{id}

Link alert

POST /v2/api/webhooks/{id}/link-alert

Getting Started

Guides

Authentication

Companies & fleet

Vehicles

Vehicle commands

Alerts

Telemetry & replay

Insights & diagnostics

Webhooks

Reference

How it works

Payload shape

Type-specific `Data` payloads

Supported alert types

Alert-scoped webhooks

Global webhooks

Request headers

Verifying the signature

Global vs alert-scoped webhooks

Delivery retries

Managing webhooks

Create

List

Get

Update

Delete

Link alert

​How it works

​Payload shape

​Type-specific Data payloads

​Supported alert types

​Alert-scoped webhooks

​Global webhooks

​Request headers

​Verifying the signature

​Global vs alert-scoped webhooks

​Delivery retries

​Managing webhooks

Create

List

Get

Update

Delete

Link alert

How it works

Payload shape

Type-specific `Data` payloads

Supported alert types

Alert-scoped webhooks

Global webhooks

Request headers

Verifying the signature

Global vs alert-scoped webhooks

Delivery retries

Managing webhooks