# Receive a Telegram webhook

Receive a Telegram update verified by the channel webhook secret header.

## Endpoint

`POST /api/v1/channels/telegram/webhook`

## Authentication

| 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

Telegram sends X-Telegram-Bot-Api-Secret-Token with the configured webhook secret; Operade verifies it before processing the update.

```json
{
  "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 | — | — |

### Response example

HTTP 4XX
No finite representative body is available for this response schema.

## Errors

Reviewed common and route-declared errors are summarized here; the list is not exhaustive. Start with the [distributed error index](/docs/reference/api/errors) 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. |

## Related operations

No related operations in this resource group.