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

​
How it works

  1. Create a webhook via POST /api/v2/webhooks. You receive a plaintext HMAC secret in the response — save it securely, it is returned only once.
  2. Link one or more alert configurations to the webhook (via alertIds on creation, or later via POST /api/v2/webhooks/{id}/link-alert). Alternatively, set isGlobal: true to receive all alerts for your company.
  3. 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": { ... }
}
FieldTypeDescription
alertTypestringHuman-readable alert type label
vehicleIdintegerLegacy vehicle ID
vehicleNamestringVehicle display name
position.lat / position.lngnumberGPS coordinates at trigger
directionintegerHeading in degrees (0–359)
timestampdatetimeUTC trigger time
addressobject | nullReverse-geocoded location
dataobject | nullType-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 /api/v2/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:
HeaderDescription
X-Telemax-Signaturesha256=<hex> — HMAC-SHA256 signature of the raw request body
X-Telemax-DeliveryUUID 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)

​
Global vs alert-scoped webhooks

Global (isGlobal: true)Alert-scoped
Fires forAll alert types across the company and sub-companiesOnly the linked alert configurations
alertIds requiredNoYes (at least one)
Mixed payload typesYes — data shape varies per alertPredictable 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 /api/v2/webhooks

List

GET /api/v2/webhooks

Get

GET /api/v2/webhooks/

Update

PUT /api/v2/webhooks/

Delete

DELETE /api/v2/webhooks/

Link alert

POST /api/v2/webhooks//link-alert