How verify request of webhook are from Telegram?

Question

I have a Telegram bot that is set to work with Telegram webhook mechanism but how trust requests and know if they are from Telegram?

base on Telegram docs I find out there is two way:

• limit them to telegam ip (this is dirty, if for some reason telegam change its ip my bot will shut down so it is not a option)
• set a private long url for webhook so only my server and telegram know the url (I don't think it's a good enough solution to secure my webhook, urls are public if for some reason my url leak, everyone can pretend they are telegram and send fake requests)

these two was what I found is there anything I miss? why Telegram don't provide a rsa public key like OAuth2 or some trusted token or signature like Github for its webhook? is private url enough for security?

Ruthanneruthe

Answer 1

As of Bot API 6.1, there is a new optional secret_token string parameter to the setWebhook method:

A secret token to be sent in a header “X-Telegram-Bot-Api-Secret-Token” in every webhook request, 1-256 characters. Only characters A-Z, a-z, 0-9, _ and - are allowed. The header is useful to ensure that the request comes from a webhook set by you.

So you would pass this parameter when setting the webhook, then on each incoming request you would verify that the X-Telegram-Bot-Api-Secret-Token header matches.

Darwinism

Answer 2

Regarding the IP limit here:

Accepts incoming POSTs from subnets 149.154.160.0/20 and 91.108.4.0/22 on port 443, 80, 88, or 8443.

If you decide to limit traffic to our specific range of addresses, keep an eye on this document whenever you seem to run into trouble. Our IP-range might change in the future.

Telegram always inform users about important changes before applying them, so if you subscribe to their BotNews channel, you wouldn't miss news about the ip-range changes. So I think it's still is a good option.

---

Regarding

urls are public if for some reason my url leak, everyone can pretend they are telegram and send fake requests

Your argument is correct I think, but the possibility of a private url leakage is not that high and it is somehow brute-force safe. Based on what we know about how Telegram cares about security, if they receive reports of fake webhook requests they would offer solutions.

Though if you're still worried, you can use a Local Bot Api Server where you could only trust your internal ip address.

Rigamarole

you are right it is not a big hole... after I created this question, searched about ways private url may be a security problem and found out it is bad when there is possibility private url use by another sites or web browsers which is not our case. but still private urls by default pretend as a regular url so they will print in webserver access and bug report logs. Anyone who use telegram webhook must be aware to disable them to avoid problems in feature this was only serious problem I found with private url... And I think they must add some warning about this in their documents – Ruthanneruthe

Answer 3

You could attach a secret auth token as a query parameter to your webhook's URL. i.e. https://example.com/telegram_webhook?auth=12345 that you would then verify on your server.

This is somewhat more secure if you worry that your base URL is too easy to obtain.

...most ideally, you'd want Mutual TLS (mTLS), but I'm not aware of Telegram supporting that.

Polished