Receive a Telegram webhook
Receive a Telegram update verified by the channel webhook secret header.
Endpoint
POST
/api/v1/channels/telegram/webhookAuthentication
| Operation class | Authentication | Minimum role | API key |
|---|---|---|---|
| provider-callback | Telegram webhook secret in X-Telegram-Bot-Api-Secret-Token. | none | Not allowed |
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
x-telegram-bot-api-secret-token | header | string or null | No | — |
Request body
application/json request schema
| Field path | Type | Reference | Format | Nullable | Required | Enum | Description |
|---|---|---|---|---|---|---|---|
$ | object | — | — | No | Yes | — | — |
Example
Provider payload contract
Telegram sends X-Telegram-Bot-Api-Secret-Token with the configured webhook secret; Operade verifies it before processing the update.
{
"message": {
"chat": {
"id": 300001,
"type": "private"
},
"message_id": 200001,
"text": "Hello"
},
"update_id": 100001
}Responses
| Status | Description | Content |
|---|---|---|
4XX | Handled client error | application/json: ErrorResponse |
200 | Successful Response | No body |
502 | Bad Gateway | application/json: ErrorResponse |
4XX application/json response schema
| Field path | Type | Reference | Format | Nullable | Required | Enum | Description |
|---|---|---|---|---|---|---|---|
$ | object | ErrorResponse | — | No | Yes | — | — |
error | object | ErrorItem | — | No | Yes | — | — |
error.code | string | — | — | No | Yes | — | — |
error.details | object | — | — | No | No | — | — |
error.message | string | — | — | No | Yes | — | — |
502 application/json response schema
| Field path | Type | Reference | Format | Nullable | Required | Enum | Description |
|---|---|---|---|---|---|---|---|
$ | object | ErrorResponse | — | No | Yes | — | — |
error | object | ErrorItem | — | No | Yes | — | — |
error.code | string | — | — | No | Yes | — | — |
error.details | object | — | — | No | No | — | — |
error.message | string | — | — | No | Yes | — | — |
Errors
Reviewed common and route-declared errors are summarized here; the list is not exhaustive. Start with the distributed error index to find each code's canonical domain page.
| Status | Code | Description |
|---|---|---|
422 | validation_failed | The request did not pass field or business validation. |
502 | channel_upstream_failed | Telegram temporarily rejected an outbound channel action. |