Telegram bot webhook Update payload example

Telegram Bot API · event: Update (message) · content type: application/json

This is a representative sample — fake IDs, real structure. To see a payload with your data, point the provider at a capture URL (button below).

See it live, not frozen

One click creates a free capture bin with this exact payload already in it — pretty-printed, headers inspectable, replayable to your own endpoint:

Then paste the bin's URL into Telegram Bot API's webhook settings to capture a real delivery. No signup.

Headers

content-type: application/json
x-telegram-bot-api-secret-token: my-webhook-secret-1

Body

{
  "update_id": 903761024,
  "message": {
    "message_id": 517,
    "from": {
      "id": 5216849302,
      "is_bot": false,
      "first_name": "Ada",
      "username": "ada_lovelace",
      "language_code": "en"
    },
    "chat": {
      "id": 5216849302,
      "first_name": "Ada",
      "username": "ada_lovelace",
      "type": "private"
    },
    "date": 1787990000,
    "text": "/start",
    "entities": [
      {
        "offset": 0,
        "length": 6,
        "type": "bot_command"
      }
    ]
  }
}

Things that bite people

There is no signature scheme at all — the X-Telegram-Bot-Api-Secret-Token header (only sent if you passed secret_token to setWebhook) is the entire authentication. Compare it server-side; without it, anyone who finds your URL can forge updates.
Webhook URLs must use ports 443, 80, 88 or 8443 only, and deliveries come from Telegram's published subnets (149.154.160.0/20, 91.108.4.0/22).
Exactly one field besides update_id is present per Update (message, edited_message, callback_query…) — switch on which key exists.
Running getUpdates polling while a webhook is set yields 409 Conflict — the classic "my webhook stopped working" cause. Full triage: Telegram webhook debugging.
Your HTTP response body is not a reply to the user — bots answer via separate API calls, which makes Telegram a perfect fit for capture-and-inspect debugging.

Send it yourself

Reproduce this delivery against any endpoint (your handler, a bin, staging):

$ curl -X POST https://your-endpoint.example/hook \
  -H 'content-type: application/json' \
  -H 'x-telegram-bot-api-secret-token: my-webhook-secret-1' \
 -d '{"update_id":903761024,"message":{"message_id":517,"from":{"id":5216849302,"is_bot":false,"first_name":"Ada","username":"ada_lovelace","language_code":"en"},"chat":{"id":5216849302,"first_name":"Ada","username":"ada_lovelace","type":"private"},"date":1787990000,"text":"/start","entities":[{"offset":0,"length":6,"type":"bot_command"}]}}'

← All payload examples · Related guide · Signature debugger · Docs