TSocial TSocial
Open in Telegram
Better in TelegramOpen in Telegram
TSocial planet logoTelesocial

Telesocial › Cheat sheets

Webhook Security Card: Six Things to Check

Cheat sheets · 2026-11-06 · 18+ readers

A code icon webhook URL is open to the internet. Telegram can call it, and so can anyone who finds it. These six checks keep it honest.

1. HTTPS with a real certificate

Use a valid certificate on an allowed port. Terminate TLS at a proxy or platform, never expose plain HTTP.

2. A secret header

Set secret_token in setWebhook. Telegram then adds X-Telegram-Bot-Api-Secret-Token to each request. Compare it with your stored value and return 401 if it differs.

3. Answer fast

Return 200 first, work second. Slow handlers cause retries and a growing pending count.

4. Handle repeats

The same update can arrive twice. Keep the last update_id or a table of seen ids.

5. Quiet logs

Never print the bot icon bot token, the secret or full user data. Redact URLs.

6. Watch it

Call getWebhookInfo on a schedule. Alert on last_error_message and a rising pending_update_count.

Quick test

  • Send a request without the header: expect 401.
  • Send a real message from a second account: expect a reply.
  • Stop the server briefly: updates should arrive after it returns.

Frequently asked questions

Is the secret token mandatory?

No, but skipping it leaves your endpoint open to fake updates.

How do I rotate the secret?

Accept both values for a short time, call setWebhook with the new one, then remove the old.

Can I hide the URL instead?

A hidden path helps a little but is not a substitute for the header check.

More cheat sheets

Webhook Security Card: Six Things to Check | Telesocial