Which Telegram Signature to Verify: initData, Login Widget or Webhook
· 4 min read · 18+ readers

Whenever data reaches your server and says it comes from Telegram, you must check it. Telegram offers several mechanisms, and they are easy to mix up because they all use HMAC and a bot token in some way. This guide compares the three you will meet most often so you can use the right check in the right place. Algorithms below follow the official documentation. Always verify against the current docs before shipping.
The three checks
| Where the data arrives | What proves it | Secret used |
|---|---|---|
| A Mini App opened in | hash inside initData | HMAC of the bot token with key WebAppData |
| The Login Widget on your website | hash in the returned fields | SHA-256 of the bot token |
| A bot webhook request | The X-Telegram-Bot-Api-Secret-Token header | A secret string you chose |
They protect different things. Do not substitute one for another.
1. Mini App initData
Used when a Mini App sends the user's identity to your server. The hash is an HMAC over sorted key=value lines. The secret key is HMAC_SHA256(key="WebAppData", message=bot_token). Then you HMAC the data check string with that key. See the full procedure and code in validating initData.
Also check auth_date. There is an alternative Ed25519 signature that lets third parties verify without the token.
2. Login Widget
Used when someone signs in with Telegram on your website. The secret is SHA256(bot_token), used as the HMAC key over the sorted fields excluding hash. See the Login Widget guide.
Memory aid:
- Mini App: key is the text
WebAppData, message is the token. - Login Widget: the key is the SHA-256 digest of the token.
3. Webhook secret token
Used to be sure a POST to your webhook comes from Telegram. When you call setWebhook with secret_token, Telegram sends it in a header with every update. You compare the header to your stored secret. There is no HMAC. See webhook setup.
This check does not tell you who the user is. It only tells you that the request came from Telegram for your bot.
Which one do I need
- Building a Mini App with accounts: you need the webhook check on your bot and
initDatavalidation for the app. - Building a website with Telegram sign in: you need the Login Widget check.
- Building a bot only: you need the webhook check.
- Doing all three: you need all three, with different code paths.
Shared rules
- Run verification on the server only. The token must never be in browser code.
- Compare in constant time.
- Check freshness with
auth_datewhere it exists. - Reject on any failure with a generic error and log it without printing secrets.
- Do not accept the user's id from any other field or parameter once you have verified.
- Rotate the token after any leak. See token safety.
A tiny helper to avoid mistakes
import crypto from "node:crypto";
const hmac = (key, msg) => crypto.createHmac("sha256", key).update(msg).digest();
export const miniAppSecret = (token) => hmac("WebAppData", token); // Mini Apps
export const loginWidgetSecret = (token) => crypto.createHash("sha256").update(token).digest(); // Login Widget
export const eqHex = (a, b) => a.length === b.length && crypto.timingSafeEqual(Buffer.from(a, "hex"), Buffer.from(b, "hex"));
Name them clearly and add tests with known good samples so nobody swaps them by accident.
Typical bugs
- Using the widget formula on
initData, so every check fails. - Hashing the URL-encoded string instead of decoded values.
- Skipping the webhook header check because the URL is obscure.
- Letting the front end tell the server which user it is.
- Forgetting that
initDataUnsafeis not verified.
Quick checklist
- Webhook requests verified with the secret token header.
- Mini App users verified with initData and the WebAppData secret.
- Website logins verified with the Login Widget hash and SHA-256 secret.
- All checks run on the server only.
- Hash comparison uses a constant time function.
- auth_date is checked for freshness.
- Secrets and tokens never appear in logs.
- Unit tests cover a good sample and a tampered sample for each.
Build a test set
For each check, keep one valid sample you generated yourself in a private test setup and a few broken variants: changed value, missing hash, old date. Run them in your automated tests so that a refactor cannot silently weaken authentication. Never paste real user data into tests.
Frequently asked questions
Can I use one check for everything?
No. They guard different channels, and each uses its own rule.
Do I need the bot token to verify?
For HMAC based checks, yes. The Ed25519 option for Mini Apps avoids sharing the token with a third party.
What if verification fails only on some users?
Check for encoding differences, special characters in names and clock skew on auth_date.
Is a secret URL path enough for webhooks?
No. Use the secret header too.
Related guides

Validate Telegram Mini App initData on Your Server
Why initData must be verified, how the HMAC check works step by step, a Node.js example, auth_date freshness and common mistakes.

Telegram Login Widget: Sign In With Telegram on a Website
Add Log in with Telegram to your website: /setdomain in BotFather, the widget script, the data you receive, server-side hash verification and common mistakes.

Set Up a Telegram Webhook with HTTPS and a Secret Token
Register a webhook with setWebhook, protect it with secret_token, check getWebhookInfo, pick allowed_updates and handle retries, with a short Node example.

Keep Your Telegram Bot Token Safe (and What to Do if It Leaks)
A bot token is a password. Learn where tokens leak, how to store them, how to rotate with /revoke, how to detect misuse and a leak response checklist.

Connect Your Backend to a Telegram Bot: A Practical Architecture
How to wire a bot to your own backend: receiving updates, mapping Telegram users to accounts, queues, database design, idempotency and safe deploys.

A Telegram Webhook on AWS Lambda or a Small Server
Two ways to receive Telegram updates: an AWS Lambda function URL and a tiny Node server behind HTTPS, with secret token checks, fast replies and queues.
More in Build on Telegram
- Add a Bot as Channel Admin and Post to Your Channel
- Bot Privacy Mode and Group Admin Rights Explained
- BotFather Commands: What Each One Does
- Common Telegram Bot Errors and How to Fix Them
All topics: Build on Telegram · Guide index · Explore Telegram · About TSocial