Webhook Security Card: Six Things to Check
Cheat sheets · 2026-11-06 · 18+ readers
A 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 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.