Webhook ربات تلگرام چیست؟ آموزش تنظیم و استفاده از Webhook

یکی از روش‌های اصلی دریافت این Updateها استفاده از
Webhook
است. در این روش به‌جای اینکه برنامه مرتباً از Telegram بپرسد
«پیام جدیدی وجود دارد؟»، Telegram هنگام ایجاد Update آن را مستقیماً
به یک آدرس HTTPS روی سرور شما ارسال می‌کند.

در این آموزش Webhook ربات تلگرام را از پایه بررسی می‌کنیم؛
از تفاوت آن با Long Polling و تنظیم
setWebhook
گرفته تا امنیت Endpoint، استفاده از
secret_token،
بررسی خطاها و حذف Webhook.

اگر هنوز با ساختار کلی Bot API و نحوه ساخت Bot آشنا نیستید، ابتدا مقاله
آموزش ساخت ربات تلگرام از صفر
را مطالعه کنید.

Webhook ربات تلگرام چیست؟

Webhook یک URL روی Backend شماست که Telegram می‌تواند Updateهای جدید ربات
را به آن ارسال کند.

برای مثال ممکن است Endpoint ربات شما چنین آدرسی داشته باشد:

https://example.com/telegram/webhook

بعد از ثبت این URL با
setWebhook،
وقتی کاربر برای Bot پیام ارسال کند یا یکی از Updateهای موردنظر ایجاد شود،
Telegram یک درخواست HTTP POST به این Endpoint ارسال می‌کند.

Body درخواست شامل یک شیء JSON از نوع
Update
است که Backend می‌تواند آن را پردازش کند.

Telegram Update چیست؟

Update ساختاری است که یک رویداد جدید مرتبط با Bot را توصیف می‌کند.

Update الزاماً فقط یک پیام متنی نیست و بسته به قابلیت‌های ربات می‌تواند
انواع مختلفی از داده را در اختیار Backend قرار دهد.

برای مثال:

• پیام جدید کاربر
• ویرایش پیام
• کلیک روی Inline Keyboard
• Callback Query
• Inline Query
• تغییر وضعیت عضویت
• درخواست پیوستن به Chat
• رویدادهای پرداخت

بنابراین هنگام نوشتن Webhook Handler نباید فرض کنید تمام Updateها دارای
فیلد
message
یا
text
هستند.

تفاوت Webhook و getUpdates چیست؟

Telegram دو روش اصلی برای دریافت Updateهای Bot در Bot API ارائه می‌دهد:

• getUpdates با Long Polling
• Webhook

تفاوت اصلی در این است که چه کسی ارتباط را برای دریافت Update آغاز می‌کند.

آیا Webhook و getUpdates همزمان کار می‌کنند؟

خیر.

زمانی که برای Bot یک Webhook فعال باشد،
getUpdates
برای دریافت Updateهای همان Bot کار نخواهد کرد.

بنابراین هنگام تغییر معماری ربات از Long Polling به Webhook یا برعکس،
باید وضعیت فعلی Bot را در نظر بگیرید.

برای Webhook ربات تلگرام به چه چیزهایی نیاز داریم؟

برای راه‌اندازی Webhook عمومی معمولاً به این موارد نیاز دارید:

• Bot Token معتبر
• Backend یا Web Server
• یک Endpoint عمومی
• HTTPS و TLS معتبر
• دامنه یا زیرساخت قابل دسترس از اینترنت
• کدی برای پردازش Updateها

برای Production بهتر است Endpoint فقط مسئول دریافت درخواست نباشد؛
باید اعتبار درخواست، خطاها و نحوه پردازش رویدادهای تکراری یا سنگین نیز
در معماری سیستم در نظر گرفته شوند.

آدرس Webhook چه شکلی است؟

بهتر است یک Route مشخص برای Bot ایجاد کنید.

مثلاً:

https://bot.example.com/webhooks/telegram

یا:

https://example.com/api/telegram/webhook

لازم نیست عبارت خاصی در URL وجود داشته باشد.
مهم این است که Endpoint قابل دسترس، امن و مخصوص دریافت Updateهای موردنظر باشد.

آموزش تنظیم Webhook با setWebhook

برای معرفی Endpoint به Telegram از متد
setWebhook
استفاده می‌شود.

ساختار پایه درخواست:

https://api.telegram.org/bot<TOKEN>/setWebhook

Token واقعی Bot را به‌جای
<TOKEN>
قرار می‌دهید و URL را به‌عنوان پارامتر ارسال می‌کنید.

نمونه تنظیم Webhook با cURL

curl -X POST \
  "https://api.telegram.org/bot<TOKEN>/setWebhook" \
  -d "url=https://example.com/telegram/webhook"

اگر عملیات موفق باشد، Bot API نتیجه موفقیت‌آمیز برمی‌گرداند.

Token واقعی را داخل مقاله، Repository عمومی یا History قابل دسترس دیگران قرار ندهید.

تنظیم Webhook همراه secret_token

بهتر است هنگام ثبت Webhook از
secret_token
نیز استفاده کنید.

برای مثال:

curl -X POST \
  "https://api.telegram.org/bot<TOKEN>/setWebhook" \
  -d "url=https://example.com/telegram/webhook" \
  -d "secret_token=BotCore_Webhook_2026"

پس از این تنظیم، Telegram مقدار Secret را در Header مخصوص درخواست‌های Webhook
برای Endpoint ارسال می‌کند.

هدر X-Telegram-Bot-Api-Secret-Token چیست؟

اگر هنگام
setWebhook
مقدار
secret_token
تعریف کرده باشید، درخواست‌های Webhook دارای هدر زیر خواهند بود:

X-Telegram-Bot-Api-Secret-Token

Backend باید مقدار این هدر را با Secret مورد انتظار مقایسه کند و درخواست‌هایی
که مقدار معتبر ندارند رد کند.

این کار لایه مهمی برای اطمینان از این موضوع است که درخواست به Webhookای
مربوط می‌شود که خود شما ثبت کرده‌اید.

قوانین secret_token

طبق Bot API، Secret Token باید بین ۱ تا ۲۵۶ کاراکتر باشد و فقط از کاراکترهای
زیر استفاده کند:

A-Z
a-z
0-9
_
-

Secret را تصادفی و غیرقابل حدس انتخاب کنید و آن را همراه Source Code عمومی منتشر نکنید.

نمونه بررسی secret_token در PHP

نمونه آموزشی ساده:

<?php

$expectedSecret = getenv('TELEGRAM_WEBHOOK_SECRET');

$receivedSecret =
    $_SERVER['HTTP_X_TELEGRAM_BOT_API_SECRET_TOKEN'] ?? '';

if (
    !$expectedSecret ||
    !hash_equals($expectedSecret, $receivedSecret)
) {
    http_response_code(403);
    exit('Forbidden');
}

$rawBody = file_get_contents('php://input');

$update = json_decode($rawBody, true);

if (!is_array($update)) {
    http_response_code(400);
    exit('Invalid JSON');
}

// پردازش Update در این قسمت انجام می‌شود.

http_response_code(200);
echo 'OK';

این فقط یک نمونه مینیمال آموزشی است.
در پروژه Production باید Logging، Error Handling، معماری پردازش و امنیت
متناسب با پروژه نیز طراحی شوند.

چرا Endpoint باید سریع پاسخ دهد؟

Webhook بخشی از مسیر تحویل Update است و بهتر است Handler بدون دلیل
عملیات طولانی و Block کننده انجام ندهد.

اگر پردازش یک Update سنگین است، معماری بهتر می‌تواند به این شکل باشد:

1. درخواست Webhook دریافت شود.
2. اعتبار آن بررسی شود.
3. Update در Queue یا سیستم پردازش ثبت شود.
4. Endpoint سریع پاسخ موفق بدهد.
5. Worker پردازش سنگین را جداگانه انجام دهد.

البته برای ربات کوچک و عملیات بسیار ساده، چنین زیرساختی لزوماً ضروری نیست.

اگر Webhook پاسخ موفق ندهد چه می‌شود؟

Telegram انتظار پاسخ HTTP موفق از Endpoint دارد.

اگر پاسخ Webhook در محدوده موفق
2XX
نباشد، Telegram تحویل Update را ناموفق در نظر می‌گیرد و ممکن است
ارسال آن را دوباره امتحان کند.

بنابراین Endpoint باید خطاهای داخلی را مدیریت کند و نباید بدون بررسی
دائماً پاسخ‌های
500
یا سایر Status Codeهای ناموفق تولید کند.

چرا پردازش Webhook باید Idempotent باشد؟

در سیستم‌هایی که احتمال Retry وجود دارد، بهتر است پردازش یک Update
به شکلی طراحی شود که اجرای دوباره آن نتیجه مخرب ایجاد نکند.

برای مثال اگر Update مربوط به ثبت پرداخت یا فعال‌سازی اشتراک باشد،
نباید پردازش دوباره همان رویداد باعث ایجاد دو سفارش یا دو بار افزایش اعتبار شود.

یکی از روش‌ها این است که
update_id
یا شناسه رویداد مرتبط را در سطح دیتابیس یا پردازش ثبت کنید و قبل از عملیات
حساس بررسی کنید آیا قبلاً پردازش شده است یا خیر.

allowed_updates چیست؟

ممکن است ربات شما فقط به بعضی انواع Update نیاز داشته باشد.

با پارامتر
allowed_updates
می‌توان نوع Updateهایی را که می‌خواهید دریافت کنید مشخص کرد.

برای مثال:

["message", "callback_query"]

یعنی Backend فقط به پیام‌ها و Callbackهای موردنظر نیاز دارد.

نمونه setWebhook با allowed_updates

curl -X POST \
  "https://api.telegram.org/bot<TOKEN>/setWebhook" \
  -d "url=https://example.com/telegram/webhook" \
  --data-urlencode 'allowed_updates=["message","callback_query"]'

محدود کردن Updateهای دریافتی می‌تواند منطق Backend را واضح‌تر کند،
اما فقط Updateهایی را حذف کنید که مطمئن هستید پروژه به آن‌ها نیاز ندارد.

drop_pending_updates چیست؟

ممکن است هنگام تغییر Webhook تعداد زیادی Update قدیمی در صف وجود داشته باشد.

پارامتر:

drop_pending_updates

مشخص می‌کند Updateهای در انتظار حذف شوند یا خیر.

استفاده از آن باید آگاهانه باشد؛ اگر مقدار
true
قرار دهید، Updateهای Pending از دست خواهند رفت.

نمونه حذف Updateهای Pending هنگام تغییر Webhook

curl -X POST \
  "https://api.telegram.org/bot<TOKEN>/setWebhook" \
  -d "url=https://example.com/telegram/webhook" \
  -d "drop_pending_updates=true"

برای سیستم Production بدون دلیل این گزینه را فعال نکنید؛
ممکن است پیام‌ها یا رویدادهایی را که هنوز پردازش نشده‌اند از دست بدهید.

max_connections چیست؟

Telegram اجازه می‌دهد تعداد Connectionهای همزمان برای تحویل Updateها
به Webhook را کنترل کنید.

پارامتر
max_connections
بین ۱ تا ۱۰۰ قابل تنظیم است و مقدار پیش‌فرض فعلی Bot API برابر ۴۰ است.

مقدار کمتر می‌تواند فشار همزمان روی Backend را کاهش دهد و مقدار بالاتر
در زیرساخت مناسب امکان Throughput بیشتری ایجاد می‌کند.

این مقدار را بدون Benchmark و شناخت ظرفیت سرور بی‌دلیل روی حداکثر قرار ندهید.

چگونه وضعیت Webhook را بررسی کنیم؟

برای بررسی Webhook فعال از متد:

getWebhookInfo

استفاده کنید.

نمونه:

https://api.telegram.org/bot<TOKEN>/getWebhookInfo

این متد یکی از مهم‌ترین ابزارهای Debug Webhook است.

getWebhookInfo چه اطلاعاتی می‌دهد؟

اطلاعات مهم خروجی می‌تواند شامل مواردی مثل این‌ها باشد:

• URL فعلی Webhook
• تعداد Updateهای در انتظار تحویل
• IP فعلی مورد استفاده
• آخرین زمان خطای تحویل
• پیام آخرین خطا
• حداکثر Connectionهای Webhook
• نوع Updateهای فعال

اگر Bot از
getUpdates
استفاده کند و Webhook فعال نباشد، فیلد URL در
getWebhookInfo
خالی خواهد بود.

pending_update_count چیست؟

فیلد:

pending_update_count

تعداد Updateهایی را نشان می‌دهد که هنوز منتظر تحویل هستند.

اگر این عدد دائماً افزایش پیدا کند، می‌تواند نشانه این باشد که Endpoint
Updateها را با سرعت کافی یا به شکل موفق دریافت نمی‌کند.

در این حالت
last_error_message
و Logهای Backend را هم بررسی کنید.

last_error_message چیست؟

وقتی Telegram در تحویل Webhook با مشکل مواجه شود،
getWebhookInfo
می‌تواند اطلاعات آخرین خطا را نمایش دهد.

این قسمت یکی از اولین جاهایی است که هنگام از کار افتادن Webhook باید بررسی شود.

چگونه Webhook را حذف کنیم؟

اگر می‌خواهید دوباره از
getUpdates
استفاده کنید، Webhook را با متد:

deleteWebhook

حذف کنید.

مثال:

curl -X POST \
  "https://api.telegram.org/bot<TOKEN>/deleteWebhook"

حذف Webhook همراه با Pending Updates

در صورت نیاز می‌توانید هنگام حذف Webhook، Updateهای در انتظار را نیز حذف کنید:

curl -X POST \
  "https://api.telegram.org/bot<TOKEN>/deleteWebhook" \
  -d "drop_pending_updates=true"

این گزینه Updateهای Pending را پاک می‌کند؛ بنابراین در Production
فقط زمانی استفاده کنید که از حذف آن‌ها مطمئن هستید.

پورت‌های مجاز Webhook تلگرام

در Bot API عمومی، Telegram در حال حاضر این پورت‌ها را برای Webhook
پشتیبانی می‌کند:

443
80
88
8443

در بیشتر پروژه‌های معمول HTTPS استاندارد روی پورت
443
ساده‌ترین انتخاب است.

آیا Webhook بدون HTTPS کار می‌کند؟

برای Webhook عمومی Telegram باید Endpoint با HTTPS در دسترس باشد.

تنظیم صحیح TLS و Certificate بخش مهم راه‌اندازی است و فقط داشتن URL
به معنی آماده بودن Webhook نیست.

Certificate برای Webhook تلگرام

در حالت معمول بهتر است از Certificate معتبر و قابل اعتماد استفاده شود.

Telegram امکان استفاده از Certificateهای Self-signed را هم فراهم کرده،
اما در این حالت باید Public Key Certificate را هنگام
setWebhook
با پارامتر
certificate
ارسال کنید.

برای بیشتر پروژه‌های وب عادی، استفاده از Certificate معتبر و مدیریت‌شده
مسیر ساده‌تری است.

آیا localhost برای Webhook کافی است؟

Telegram باید بتواند از اینترنت به Endpoint متصل شود.
بنابراین آدرسی مثل:

http://localhost:8000/webhook

مستقیماً برای Telegram قابل دسترس نیست.

برای توسعه محلی می‌توانید از Tunnel امن HTTPS استفاده کنید یا محیط
Development جداگانه‌ای روی سرور داشته باشید.

Webhook را روی همان URL اصلی سایت قرار دهیم؟

بهتر است Route مشخصی برای پردازش Telegram داشته باشید.

مثلاً:

/api/webhooks/telegram

نه اینکه صفحه اصلی سایت یا یک صفحه معمولی WordPress مسئول دریافت
Updateهای Bot باشد.

جدا بودن Endpoint، مدیریت Route، Logging، Security و Deployment را
ساده‌تر می‌کند.

آیا WordPress برای Webhook ربات مناسب است؟

از نظر فنی می‌توان Endpoint در PHP یا حتی داخل WordPress ایجاد کرد،
اما اینکه انتخاب مناسبی باشد به معماری پروژه بستگی دارد.

برای یک ربات جدی با پردازش زیاد، Queue، Worker، دیتابیس اختصاصی و
عملیات Real-time، معمولاً بهتر است Backend ربات از سایت محتوایی جدا باشد.

در این حالت WordPress می‌تواند سایت مارکتینگ و محتوایی باشد و
Backend ربات مستقل اجرا شود.

Webhook Endpoint را چگونه امن کنیم؟

حداقل موارد زیر را در نظر بگیرید:

• استفاده از HTTPS
• بررسی secret_token
• عدم انتشار Bot Token
• اعتبارسنجی ساختار JSON
• محدود کردن عملیات حساس
• استفاده از Secretهای محیطی
• Logging امن
• عدم ثبت اطلاعات حساس در Log
• مدیریت Rate و بار سرور

آیا محدود کردن IPهای Telegram مفید است؟

Telegram در راهنمای Webhook محدوده‌های شبکه‌ای مشخصی برای ارسال درخواست‌ها
منتشر می‌کند و می‌توان در معماری‌های خاص Firewall را محدود کرد.

اما این Rangeها ممکن است در آینده تغییر کنند؛ بنابراین اگر از IP Allowlist
استفاده می‌کنید، مستندات رسمی Telegram باید مرتب بررسی شوند.

حتی در صورت محدودسازی IP، بررسی
secret_token
همچنان دفاع مفیدی در سطح Application است.

آیا Bot Token را در URL Webhook قرار دهیم؟

بعضی توسعه‌دهندگان برای غیرقابل حدس شدن مسیر، Token یا Secret دیگری را
داخل Path قرار می‌دهند.

بهتر است Bot Token اصلی را بدون ضرورت در URLهای Application تکرار نکنید.
برای تایید Webhook قابلیت رسمی
secret_token
وجود دارد.

نمونه معماری ساده Webhook

Telegram
    |
    | HTTPS POST
    v
Webhook Endpoint
    |
    |-- Verify Secret
    |
    |-- Validate Update
    |
    |-- Store / Queue
    |
    v
Application Logic
    |
    |-- Database
    |-- Payment API
    |-- Other Services
    |
    v
Telegram Bot API

Webhook برای ربات فروشگاهی

در یک
ربات فروشگاهی تلگرام
Webhook می‌تواند پیام‌ها، کلیک روی محصولات و عملیات کاربران را دریافت کند.

Backend سپس اطلاعات محصول، سبد خرید و سفارش را از دیتابیس مدیریت می‌کند.

Webhook برای ربات پرداخت

در
ربات پرداخت تلگرام
بعضی Updateهای Telegram ممکن است بخشی از فرایند خرید باشند،
اما Callback سرویس پرداخت را نباید با Telegram Webhook اشتباه گرفت.

معمولاً دو Endpoint مستقل داریم:

/webhooks/telegram
/webhooks/payment

هر کدام باید اعتبارسنجی و منطق امنیتی مخصوص سرویس خودش را داشته باشد.

Webhook برای Callback Query

زمانی که کاربر روی Inline Keyboard کلیک می‌کند، Bot می‌تواند
callback_query
دریافت کند.

اگر فقط به Message و Callback نیاز دارید، می‌توانید
allowed_updates
را متناسب با همین رویدادها تنظیم کنید.

Webhook کار نمی‌کند؛ از کجا شروع کنیم؟

برای Debug کردن مرحله‌به‌مرحله جلو بروید:

1. از getWebhookInfo وضعیت را بررسی کنید.
2. مطمئن شوید URL صحیح ثبت شده است.
3. HTTPS و Certificate را بررسی کنید.
4. مطمئن شوید Endpoint از اینترنت قابل دسترس است.
5. Log وب‌سرور را بررسی کنید.
6. Status Code پاسخ را بررسی کنید.
7. last_error_message را ببینید.
8. Firewall و Reverse Proxy را بررسی کنید.
9. Secret Token را با مقدار تنظیم‌شده تطبیق دهید.

خطای 404 در Webhook

خطای 404 معمولاً یعنی Telegram به سرور رسیده اما Route ثبت‌شده وجود ندارد
یا Reverse Proxy درخواست را به Application صحیح منتقل نمی‌کند.

URL ثبت‌شده در
getWebhookInfo
را با Route واقعی Backend مقایسه کنید.

خطای 403 در Webhook

اگر خود Application پاسخ 403 می‌دهد، معمولاً یکی از کنترل‌های دسترسی
درخواست را رد کرده است.

Secret Header، Firewall، WAF و Middlewareهای امنیتی را بررسی کنید.

خطای 500 در Webhook

پاسخ 500 معمولاً نشان‌دهنده خطای داخلی Backend است.

Exception Log، Database Connection، JSON Parsing و سرویس‌های وابسته
را بررسی کنید.

از مخفی کردن خطا بدون Log خودداری کنید؛ در Production جزئیات خطا
نباید برای کاربر خارجی نمایش داده شود، اما باید در سیستم Logging قابل بررسی باشد.

pending_update_count زیاد شده؛ مشکل چیست؟

اگر تعداد Updateهای Pending مرتب بالا می‌رود، ممکن است Endpoint نتواند
Updateها را با نرخ ورودی پردازش کند یا پاسخ‌های ناموفق بدهد.

موارد زیر را بررسی کنید:

• زمان پاسخ Endpoint
• خطاهای HTTP
• ظرفیت Backend
• Database Bottleneck
• سرویس خارجی کند
• تعداد Connectionهای همزمان

چطور Webhook را بدون پیام واقعی تست کنیم؟

می‌توانید یک نمونه Update JSON ایجاد کنید و مستقیماً به Endpoint
Development خود POST کنید.

برای مثال یک Payload ساده آموزشی:

{
  "update_id": 100001,
  "message": {
    "message_id": 10,
    "chat": {
      "id": 123456789,
      "type": "private"
    },
    "text": "/start"
  }
}

هدف این تست بررسی Parser و Application Logic شماست؛
این Payload یک Update واقعی دریافت‌شده از Telegram نیست.

Webhook در Development و Production

بهتر است محیط توسعه و Production از هم جدا باشند.

برای مثال:

Development Bot
→ dev-api.example.com

Production Bot
→ api.example.com

این کار احتمال خراب شدن Bot اصلی هنگام آزمایش Webhook یا تغییر کد را کاهش می‌دهد.

Webhook بهتر است یا Long Polling؟

Webhook ذاتاً برای همه Botها «بهتر» نیست.

اگر یک Bot کوچک یا ابزار توسعه‌ای دارید، Long Polling ممکن است بسیار ساده‌تر باشد.
اگر Backend وب پایدار دارید و معماری شما مبتنی بر HTTP Endpoint است،
Webhook می‌تواند انتخاب طبیعی‌تری باشد.

انتخاب باید بر اساس زیرساخت، مقیاس، تجربه تیم و معماری پروژه انجام شود،
نه صرفاً به این دلیل که یکی از دو روش حرفه‌ای‌تر به نظر می‌رسد.

چه زمانی Webhook انتخاب مناسبی است؟

• Backend وب دائماً در دسترس دارید.
• HTTPS و Domain مناسب دارید.
• از معماری HTTP-based استفاده می‌کنید.
• می‌خواهید Polling Loop جداگانه نداشته باشید.
• زیرساخت مناسب برای پردازش Updateها دارید.

چه زمانی getUpdates انتخاب ساده‌تری است؟

• در حال یادگیری هستید.
• Bot را روی سیستم شخصی تست می‌کنید.
• Endpoint عمومی ندارید.
• حجم پروژه پایین است.
• سادگی Deployment برایتان مهم‌تر است.

چک‌لیست Webhook ربات تلگرام

• Endpoint عمومی HTTPS آماده است.
• Bot Token در Source Code عمومی نیست.
• Webhook با setWebhook ثبت شده است.
• secret_token تنظیم شده است.
• Secret Header در Backend بررسی می‌شود.
• JSON Update قبل از استفاده Validate می‌شود.
• Endpoint پاسخ HTTP مناسب می‌دهد.
• پردازش حساس در برابر Duplicate ایمن است.
• getWebhookInfo بررسی شده است.
• Monitoring و Logging فعال است.

سوالات متداول درباره Webhook ربات تلگرام

منابع رسمی Webhook تلگرام

• 
  مستندات رسمی setWebhook
  
• 
  مستندات رسمی getWebhookInfo
  
• 
  راهنمای رسمی Telegram Webhooks