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 all alerts for your company.
When a linked alert fires, Telemax sends an HTTP POST to your URL with a signed JSON payload.

Payload shape

{
  "alertType": "Speeding",
  "vehicleId": 88421,
  "vehicleName": "Delivery Van 07",
  "position": { "lat": -33.8688, "lng": 151.2093 },
  "direction": 270,
  "timestamp": "2026-04-28T06:14:22Z",
  "address": {
    "street": "42 George St",
    "suburb": "Sydney",
    "state": "NSW",
    "postcode": "2000",
    "country": "Australia"
  },
  "data": { ... }
}

Field	Type	Description
alertType	string	Human-readable alert type label
vehicleId	integer	Vehicle ID
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
address	object \| null	Reverse-geocoded location
data	object \| null	Type-specific payload (see below)

Type-specific `data` payloads

The data field carries additional context depending on alertType: Geofence

{ "geofenceName": "Depot Zone", "isExit": true }

Ignition

{ "isStarted": true }

Low battery

{ "voltage": 11.8, "threshold": 12.0 }

Speeding

{ "speed": 127.4, "maxSpeed": 110.0 }

For all other alert types, data is null.

Supported alert types

Webhooks can be linked to alert configurations with the following type IDs (as returned by GET /v2/api/companies/{id}/alerts): 1, 2, 5, 8, 9, 10. A maximum of 50 alert configurations can be linked to a single webhook.

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 uniquely identifying this delivery attempt

Verifying the signature

Compute HMAC-SHA256(secret, rawBody) and compare the hex digest to the value after sha256= in X-Telemax-Signature. 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 = createHmac("sha256", secret).update(body).digest("hex");
  const received = header.replace("sha256=", "");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}

Global vs alert-scoped webhooks

	Global (`isGlobal: true`)	Alert-scoped
Fires for	All alert types across the company and sub-companies	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 retries failed deliveries (non-2xx response or connection error) with exponential backoff. Respond with a 2xx status as quickly as possible — perform any heavy processing asynchronously. Idempotency is guaranteed via X-Telemax-Delivery: the same UUID will not be delivered more than once per attempt window.

Managing webhooks

Create

POST /v2/api/webhooks

List

GET /v2/api/webhooks

Get

GET /v2/api/webhooks/

Update

PUT /v2/api/webhooks/

Delete

DELETE /v2/api/webhooks/

Link alert

POST /v2/api/webhooks//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

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

​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

Request headers

Verifying the signature

Global vs alert-scoped webhooks

Delivery retries

Managing webhooks