Interactive example
Telegram Update request lab
Compare a Bot API message update with the acknowledgement returned by the temporary endpoint.
- Content-Type
- application/json
- X-Telegram-Bot-Api-Secret-Token
- synthetic_webhook_secret_42
{
"update_id": 987654321,
"message": {
"message_id": 42,
"from": { "id": 100200300, "is_bot": false, "first_name": "Test User" },
"chat": { "id": 100200300, "type": "private", "first_name": "Test User" },
"date": 1785758400,
"text": "/status staging"
}
}Configured response
200 OK
Content-Type: application/json
{"ok":true,"source":"telegram-test"}Synthetic data only. Never paste production tokens, signing secrets, personal data, or payment information into a public test endpoint.
One-click test setup
Creates a temporary bucket and applies this guide's expected response. You can inspect and delete it from the dashboard.
Separate the Bot Token from the Webhook Test
A Telegram bot token authorizes Bot API calls and must never be pasted into a public request inspector. This test needs only a synthetic Update payload and a temporary HTTPS destination. Create the endpoint, send the lab JSON from curl or your own fixture runner, and inspect the exact request shape.
When you later call setWebhook, do that from your own trusted environment. Register the receiver URL there and keep the token in a secret manager. The temporary endpoint is for transport evidence, not for operating a production bot.
Inspect the Update Envelope
Telegram delivers an Update object as JSON. The object can contain different optional event fields, so code that only handles message will miss callbacks, edited messages, membership changes, and other update types. Start with one small message fixture and branch explicitly on the fields your bot supports.
The synthetic example preserves realistic nesting: update_id identifies the update, message_id identifies the message, and the from and chat objects have different meanings. Verify numbers remain numbers and that your framework does not flatten or rename keys.
- Use POST with Content-Type application/json
- Treat update_id as the delivery identifier for deduplication
- Expect different optional Update fields instead of one universal message schema
- Keep real usernames, chat IDs, bot tokens, and message text out of shared fixtures
Verify the Secret-Token Header
The setWebhook secret_token parameter asks Telegram to include X-Telegram-Bot-Api-Secret-Token with every webhook request. Telegram limits that value to 1–256 characters from letters, numbers, underscore, and hyphen. The lab header follows that shape but is not a credential.
Your production receiver should reject a missing or incorrect value before doing business work. A secret URL path can add obscurity, but the documented header provides an explicit request check. Never reuse the synthetic value from this page.
Test Acknowledgement and Redelivery
The one-click endpoint returns 200 with a small JSON acknowledgement. Telegram only needs a successful HTTP response; the response body is useful to your test client but does not send a bot message. Bot replies are separate Bot API calls.
Telegram documents repeated delivery attempts after an unsuccessful response but does not publish a precise public retry schedule. Use controlled non-2xx responses to observe behavior in your own test bot, and make update handling idempotent instead of assuming one delivery.
Diagnose Common Telegram Failures
If no request arrives, inspect getWebhookInfo for the current URL, pending update count, and last error. Confirm outbound connectivity and certificate requirements. Also confirm that a polling process is not competing with webhook mode.
If requests arrive but the bot does nothing, compare the captured raw JSON with the parser input and verify the secret-token check. Return quickly after accepting valid updates, move slow work to a queue, and delete the temporary bucket when the test is complete.
- Wrong URL or stale registration: call getWebhookInfo and register the exact new HTTPS URL
- 401 or 403 from your receiver: verify the secret-token header comparison
- Repeated updates: deduplicate by update_id before side effects
- Slow handling: acknowledge first and process asynchronously
Common questions
Frequently asked questions
- Does Telegram require an HTTPS webhook URL?
- Yes. The Bot API setWebhook method accepts an HTTPS URL. WebhookTest.net supplies HTTPS, but use only synthetic updates here and keep the bot token out of the endpoint URL and captured data.
- How do I verify a Telegram webhook request?
- Set a secret_token when calling setWebhook, then compare the X-Telegram-Bot-Api-Secret-Token header using a constant-time comparison in your real receiver. The value in this lab is synthetic.
- Why is my bot still using getUpdates?
- Telegram documents getUpdates and webhooks as mutually exclusive. Remove the webhook before polling, or stop polling and set the webhook again when testing push delivery.
Primary sources
Official references
Try it with a real request
Turn the guide into a test.
Open a temporary endpoint, send your payload, and inspect exactly what arrived.
Open the tester