TSocial TSocial
Open in Telegram
Better in TelegramOpen in Telegram

Which Telegram Signature to Verify: initData, Login Widget or Webhook

· 4 min read · 18+ readers

Which Telegram Signature to Verify: initData, Login Widget or Webhook: TSocial guide cover card

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 icon 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 arrivesWhat proves itSecret used
A Mini App opened in Telegramhash inside initDataHMAC of the bot token with key WebAppData
The Login Widget on your websitehash in the returned fieldsSHA-256 of the bot token
A bot webhook requestThe X-Telegram-Bot-Api-Secret-Token headerA secret string you chose

They protect different things. Do not substitute one for another.

1. Mini App initData

Used when a Mini App icon (grid) 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 code icon 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 initData validation 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_date where 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 initDataUnsafe is 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 channel megaphone icon 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

More in Build on Telegram

All topics: Build on Telegram · Guide index · Explore Telegram · About TSocial

Which Telegram Signature to Verify: initData, Login Widget or Webhook | TSocial