Alert webhooks message-webhooks
DingTalk, Feishu, WeCom, Telegram and generic JSON alert outputs; several can be configured, and addresses and secrets show only the last 4 characters.
Pick an endpoint to see its example call on the right.
Authentication
Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.
X-API-Key
Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).
Conventions
Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.
Times are RFC 3339 (UTC); amounts are in cents.
Writes return 200/201/204 on success; duplicates of a unique key return 409.
/api/v2/message-webhooksList alert webhooks
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
/api/v2/message-webhooksCreate alert webhook
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
chat_id | string | Telegram chat (numeric id or @channel name). |
created_atRequired | string | Created at |
enabled | boolean | Whether it is enabled; disabled ones are skipped. Enabled by default. |
events | string[] | Event types to receive: alert (platform alerts) and ticket (tickets). Omitted on create means all; omitted on update keeps the current value; an empty array is rejected with 422. |
idRequired | integer | Record ID |
kindRequired | string | Kind: dingtalk, feishu, wecom, telegram or generic JSON. |
last4 | string | Last 4 characters of the address (the token for Telegram), for recognition only. |
nameRequired | string | Name, unique across all webhooks. |
secret | string | Bot token for Telegram (required); signing secret for the others (optional). Write-only, never echoed. |
updated_atRequired | string | Updated at |
url | string | Bot URL (https, public; required for DingTalk, Feishu, WeCom and generic; unused for Telegram). Write-only, never echoed. |
/api/v2/message-webhooks/testTest unsaved alert webhook
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
chat_id | string | Telegram chat (numeric id or @channel name). |
id | integer | Record ID |
kindRequired | string | Kind: dingtalk, feishu, wecom, telegram or generic JSON. |
secret | string | Bot token for Telegram (required); signing secret for the others (optional). Write-only, never echoed. |
url | string | Bot URL (https, public; required for DingTalk, Feishu, WeCom and generic; unused for Telegram). Write-only, never echoed. |
/api/v2/message-webhooks/{id}Update alert webhook
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
chat_id | string | Telegram chat (numeric id or @channel name). |
created_atRequired | string | Created at |
enabled | boolean | Whether it is enabled; disabled ones are skipped. Enabled by default. |
events | string[] | Event types to receive: alert (platform alerts) and ticket (tickets). Omitted on create means all; omitted on update keeps the current value; an empty array is rejected with 422. |
idRequired | integer | Record ID |
kindRequired | string | Kind: dingtalk, feishu, wecom, telegram or generic JSON. |
last4 | string | Last 4 characters of the address (the token for Telegram), for recognition only. |
nameRequired | string | Name, unique across all webhooks. |
secret | string | Bot token for Telegram (required); signing secret for the others (optional). Write-only, never echoed. |
updated_atRequired | string | Updated at |
url | string | Bot URL (https, public; required for DingTalk, Feishu, WeCom and generic; unused for Telegram). Write-only, never echoed. |
/api/v2/message-webhooks/{id}Delete alert webhook
Authentication: Admin only
/api/v2/message-webhooks/{id}/testTest saved alert webhook
Authentication: Admin only
Alert webhooks object
| Field | Type | Description |
|---|---|---|
chat_id | string | Telegram chat (numeric id or @channel name). |
created_at | string | Created at |
enabled | boolean | Whether it is enabled; disabled ones are skipped. Enabled by default. |
error | string | Error message when the test failed. |
events | string[] | Event types to receive: alert (platform alerts) and ticket (tickets). Omitted on create means all; omitted on update keeps the current value; an empty array is rejected with 422. |
id | integer | Record ID |
kind | string | Kind: dingtalk, feishu, wecom, telegram or generic JSON. |
last4 | string | Last 4 characters of the address (the token for Telegram), for recognition only. |
name | string | Name, unique across all webhooks. |
ok | boolean | Whether the test send succeeded. |
secret | string | Bot token for Telegram (required); signing secret for the others (optional). Write-only, never echoed. |
updated_at | string | Updated at |
url | string | Bot URL (https, public; required for DingTalk, Feishu, WeCom and generic; unused for Telegram). Write-only, never echoed. |
Responses and errors
Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.
{
"id": 1,
"name": "example"
}{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}{
"code": "validation_failed",
"detail": "Invalid request parameters",
"errors": [
{
"code": "required",
"field": "/name",
"message": "name is required"
}
],
"request_id": "0123456789abcdef",
"status": 422,
"title": "Unprocessable Entity",
"type": "about:blank"
}