> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telemax.com.au/llms.txt
> Use this file to discover all available pages before exploring further.
# Update webhook
> Updates the URL, active state, and linked alerts of a webhook.
### Overview
Updates a webhook. The request body replaces the entire webhook configuration — include all fields you want to keep, not just the ones you are changing.
**Rate limit:** 4 req/s · 20/min · 600/hr · 14,400/day
### Endpoint
`PUT /v2/api/webhooks/{id}`
### Path parameters
Webhook ID.
### Request body
```json theme={null}
{
"url": "https://your-server.example.com/new-endpoint",
"alertIds": [101, 103],
"isActive": true,
"isGlobal": false
}
```
| Field | Type | Required | Description |
| -------- | ---------- | ----------------------- | ------------------------------- |
| url | string | Yes | Destination URL |
| alertIds | integer\[] | Yes (unless `isGlobal`) | Alert configuration IDs to link |
| isActive | boolean | No | Enable or disable deliveries |
| isGlobal | boolean | No | Enable global delivery |
### Response
**200 OK** — `WebhookDto` with updated values.
### Error responses
| Status | Meaning |
| ------ | ---------------------------------------------------------------------------------------- |
| 401 | Missing or invalid token |
| 404 | Webhook or alert ID not found |
| 422 | `isGlobal` is false and `alertIds` is empty, or `alertIds` contains more than 50 entries |
```bash theme={null}
curl -X PUT "https://api.telemax.com.au/v2/api/webhooks/7" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{"url":"https://your-server.example.com/new-endpoint","alertIds":[101],"isActive":false,"isGlobal":false}'
```
## OpenAPI
````yaml openapi.yaml PUT /v2/api/webhooks/{id}
openapi: 3.1.0
info:
title: Telemax External API (V2)
version: '2026-04-14'
description: >
Telemax External API — fleet telemetry, vehicle commands, and integrations.
**Base URL:** `https://api.telemax.com.au`
**Authentication:** All routes require a `Bearer` JWT unless marked
`[AllowAnonymous]`.
Obtain tokens via `POST /v2/api/authentication/token/api-key`.
**RESTful architecture:** V2 uses standard HTTP methods (GET, POST, PUT,
DELETE) with
resource-based routes and consistent pagination via `page` and `pageSize`
query parameters.
**API versioning:** All responses will include an `X-API-Version` header
containing the
date-based version string (e.g. `2026-04-28`). See the
[Changelog](/v2/changelog) for
the deprecation policy and version history.
For full documentation including error handling, pagination, and known field
quirks, see [docs.telemax.com.au](https://docs.telemax.com.au).
servers:
- url: https://api.telemax.com.au
security:
- BearerAuth: []
paths:
/v2/api/webhooks/{id}:
put:
summary: Update webhook (V2)
description: >-
Replaces the full configuration of an existing webhook. See `POST
/v2/api/webhooks` for the supported alert type allowlist.
parameters:
- name: id
in: path
required: true
schema:
type: integer
example: 7
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- url
- alertIds
properties:
url:
type: string
format: uri
alertIds:
type: array
items:
type: integer
description: >-
IDs of alerts to subscribe to. Must be of a supported type
(see POST /v2/api/webhooks). Required when `isGlobal` is
false.
isActive:
type: boolean
isGlobal:
type: boolean
responses:
'200':
description: Successful response
content:
application/json:
example:
id: 42
url: https://webhook.site/qa-telemax-test1
alertIds:
- 4261
isActive: false
isGlobal: false
createdAt: '2026-05-29T10:33:22'
warning: null
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: >-
**404 Not Found** — The requested webhook does not exist or is not
accessible.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
type: RESOURCE
code: NOT_FOUND
description: Webhook was not found.
requestId: 0HNLTALNU4DE2:00000003
docUrl: https://docs.telemax.com.au/errors/not-found
'422':
description: >-
**422 Unprocessable Entity** — `isGlobal` is false and `alertIds` is
empty, or `alertIds` contains more than 50 entries.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
emptyAlertIds:
summary: alertIds required when not global
value:
type: VALIDATION_ERROR
code: INVALID_INPUT
description: At least one alert ID is required.
requestId: 0HNLTALNU4DE2:00000001
docUrl: https://docs.telemax.com.au/errors/invalid-input
tooManyAlerts:
summary: Too many alert IDs
value:
type: VALIDATION_ERROR
code: INVALID_INPUT
description: A webhook cannot be linked to more than 50 alerts.
requestId: 0HNLTALNU4DE2:00000004
docUrl: https://docs.telemax.com.au/errors/invalid-input
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
components:
responses:
Unauthorized:
description: >
**401 Unauthorized** — JWT is missing, expired, or malformed.
The JWT bearer middleware rejects the request before it reaches the
controller.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
type: AUTHENTICATION
code: INVALID_CREDENTIALS
description: The provided API key is invalid or does not exist.
requestId: 0HNLTALNU4DCO:00000004
docUrl: https://docs.telemax.com.au/errors/invalid-credentials
Forbidden:
description: >
**403 Forbidden** — Token is valid but the caller does not have access
to the requested company or vehicle.
Tokens issued for one company cannot access resources scoped to a
different company in the hierarchy.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
type: AUTHORIZATION
code: INVALID_SCOPE
description: >-
The provided token does not have permission to access this
resource.
requestId: 50e5c5f7-ccae-4ab6-b070-56d6645ceb1e
docUrl: https://docs.telemax.com.au/errors/invalid-scope
TooManyRequests:
description: >
**429 Too Many Requests** — Rate limit exceeded. Check the Retry-After
header for the number of seconds to wait before retrying.
Use exponential backoff: wait Retry-After seconds, then double the
interval on each subsequent 429.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
type: RATE_LIMIT
code: RATE_LIMIT_EXCEEDED
description: Too many requests. Please slow down.
requestId: req_6d2f8b4a
docUrl: https://docs.telemax.com.au/errors/rate-limit-exceeded
InternalServerError:
description: >
**500 Internal Server Error** — An unexpected error occurred. Include
the requestId when contacting support.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
type: SERVER_ERROR
code: INTERNAL_SERVER_ERROR
description: An unexpected error occurred. Please try again later.
requestId: req_1e5a3c7d
docUrl: https://docs.telemax.com.au/errors/internal-server-error
schemas:
ApiError:
type: object
description: Standard error response returned by all API endpoints.
properties:
type:
type: string
description: >-
Error category (e.g. AUTHENTICATION, AUTHORIZATION, RESOURCE,
VALIDATION_ERROR, RATE_LIMIT, SERVER_ERROR).
example: AUTHENTICATION
code:
type: string
description: Machine-readable error code within the category.
example: INVALID_CREDENTIALS
description:
type: string
description: Human-readable explanation of the error and how to resolve it.
example: The provided API key is invalid or does not exist.
requestId:
type: string
description: Unique request identifier for support correlation.
example: req_7f3a2b1c
docUrl:
type: string
format: uri
description: Link to the relevant error documentation page.
example: https://docs.telemax.com.au/errors/invalid-credentials
required:
- type
- code
- description
headers:
X-RateLimit-Limit:
description: >-
Maximum number of requests allowed per minute for this token. **Not yet
active** — this header will be added once the rate-limit middleware is
deployed. See the [Changelog](/v2/changelog) for the rollout date.
schema:
type: integer
example: 60
X-RateLimit-Remaining:
description: >-
Number of requests remaining in the current rate limit window. **Not yet
active** — see `X-RateLimit-Limit`.
schema:
type: integer
example: 47
X-RateLimit-Reset:
description: >-
Unix timestamp (seconds) at which the current rate limit window resets.
**Not yet active** — see `X-RateLimit-Limit`.
schema:
type: integer
example: 1746000060
Retry-After:
description: Number of seconds to wait before retrying after a 429 response.
schema:
type: integer
example: 30
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >
JWT Bearer token obtained from `POST
/v2/api/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.
````