Skip to main content
POST
/
api
/
v2
/
webhooks
Create webhook (V2)
curl --request POST \
  --url https://api.telemax.com.au/api/v2/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://your-server.example.com/telemax-webhook",
  "alertIds": [
    101,
    102
  ],
  "isActive": true,
  "isGlobal": false
}
'
{
  "secret": "0ABFAA308801519BFA69ECBC050AACDD567D46B042C85CD08171E4F327E71981",
  "id": 41,
  "url": "https://webhook.site/qa-telemax-test1",
  "alertIds": [],
  "isActive": false,
  "isGlobal": true,
  "createdAt": "2026-05-29T10:33:21",
  "warning": null
}

​
Overview

Creates a webhook for the authenticated company. The plaintext HMAC signing secret is included in the response only on creation — it is never returned again. Store it securely.
Rate limit: 20 requests per 60 seconds per token.

​
Endpoint

POST /api/v2/webhooks

​
Request body

{
  "url": "https://your-server.example.com/telemax-webhook",
  "alertIds": [101, 102],
  "isActive": true,
  "isGlobal": false
}
FieldTypeRequiredDescription
urlstringYesDestination URL (must be HTTPS; internal/private IPs rejected)
alertIdsinteger[]Yes (unless isGlobal)Alert configuration IDs to link (from GET /api/v2/companies/{id}/alerts)
isActivebooleanNoWhether deliveries are enabled (default true)
isGlobalbooleanNoFire for all company alerts regardless of alertIds (default false)

​
Response

200 OK — CreateWebhookResponse (extends WebhookDto)
FieldTypeDescription
idintegerWebhook ID
urlstringDestination URL
alertIdsinteger[]Linked alert configuration IDs
isActivebooleanWhether the webhook is active
isGlobalbooleanWhether global delivery is enabled
createdAtdatetimeUTC creation timestamp
secretstringPlaintext HMAC-SHA256 signing secret — store it now, not returned again
warningstring | nullSet when linked alerts have different types (payloads will have different data shapes)

​
Example response

{
  "id": 7,
  "url": "https://your-server.example.com/telemax-webhook",
  "alertIds": [101],
  "isActive": true,
  "isGlobal": false,
  "createdAt": "2026-04-28T07:00:00Z",
  "secret": "a3f8e1b2c4d5...",
  "warning": null
}

​
Error responses

StatusMeaning
401Missing or invalid token
422Alert ID not found, unsupported alert type, or more than 50 alert IDs
429Rate limit exceeded
500Unexpected server error
curl -X POST "https://api.telemax.com.au/api/v2/webhooks" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-server.example.com/hook","alertIds":[101],"isActive":true,"isGlobal":false}'

Authorizations

​
Authorization
string
header
required

JWT Bearer token obtained from POST /api/v2/authentication/token/api-key.

Lifetime: ~24 hours (86,399 seconds). Cache the token and reuse it. Re-authenticate 5 minutes before expiry.

Scoping: API key tokens are scoped to the company the key belongs to and may restrict access to a vehicle allowlist and/or action set (see token claims).

No refresh endpoint — re-authenticate with your API key when the token expires.

Body

application/json
​
url
string<uri>
required
Example:

"https://your-server.example.com/telemax-webhook"

​
alertIds
integer[]
required

IDs of alerts to subscribe to. Must be of a supported type (see endpoint description). Required when isGlobal is false.

Example:
[101, 102]
​
isActive
boolean
default:true
​
isGlobal
boolean
default:false

Response

Successful response