
به اشتراک بگذارید

به اشتراک بگذارید
تصور رایج این است که وبهوک فقط یک نشانی در تنظیمات سرویس است. این تصور فقط از سمت فرستنده میگوید Webhook چیست. از سمت سرور شما، قراری دوطرفه است: سرویس دیگر با هر رویداد یک درخواست HTTPS POST به سرور شما میفرستد و سرور باید فرستنده را بسنجد و زود جواب بدهد. خرابیها هم بیشتر همینجا رخ میدهند.
| حالت خرابی | نشانه | رفع |
|---|---|---|
| زنجیره ناقص گواهی | لاگ nginx خالی، خطای تحویل در تلگرام | خط ssl_certificate روی fullchain.pem |
| پورت نامجاز | درخواستی به سرور نمیرسد | تلگرام: 443، 80، 88، 8443؛ بله: 443 و 88 |
| گواهی تاریخگذشته | قطع ناگهانی تحویل | certbot renew --dry-run |
| پاسخ کند یا خطادار | احتمال پردازش دوباره یک پیام | اول کد 200، بعد صف |
| نبود سنجش فرستنده | اجرای درخواست جعلی | هدر مخفی یا امضای HMAC |
💡 گیرنده وبهوک چهار کار دارد
فرستنده رویداد را به نشانی HTTPS شما میفرستد و پاسخ 2xx میخواهد.
✅ زنجیره گواهی، سرعت پاسخ، سنجش فرستنده و حذف تکراریها را از پیش بیازمایید.
✅ بله برای setWebhook فقط url را مستند کرده است.
ثبت نشانی نیمه آسان کار است. یک فراخوانی. نیمه سخت، درخواستهایی است که از آن لحظه میرسند و ممکن است در دستدهی TLS رد شوند یا دو بار بیایند. برنامهای که این درخواستها را تحویل میگیرد، روی همان سروری مینشیند که میزبانی ربات بله آمادهاش کرده است.
📌 پنج خرابی سمت گیرنده
◀️ سرور شما شنونده است
◀️ گواهی و پورت؛ خطاهای تحویل
◀️ دریافت با Nginx و جواب فوری
◀️ تشخیص درخواست جعلی و تکراری

با کاری که Webhook جایش را میگیرد، یعنی دریافت دورهای (Polling)، راحتتر میشود فهمید Webhook چیست. آنجا برنامه خودش مدام سراغ API میرود. در وبهوک جهت برعکس است: پیامرسان یا درگاه رویداد را خودش به نشانی شما POST میکند.
نام متدهای بله همان نامهای Bot API تلگرام است، ولی پارامترها و پورتها نه. جدول زیر از مستندات رسمی هر دو در آبان ۱۴۰۵ است: Bot API تلگرام و مستندات بازوی بله.
| مورد | تلگرام | بله |
|---|---|---|
| نشانی متدها | https://api.telegram.org/bot<token>/METHOD_NAME | https://tapi.bale.ai/bot<token>/METHOD_NAME |
| پارامترهای setWebhook | هفت پارامتر: url، certificate، ip_address، max_connections، allowed_updates، drop_pending_updates و secret_token | فقط url |
| پورتهای مجاز | 443، 80، 88، 8443 | 443 و 88 |
| هدر مخفی | X-Telegram-Bot-Api-Secret-Token | مستند نشده |
| تکرار ارسال ناموفق | برای پاسخ غیر 2xx، تا «تعداد معقولی» تلاش | مستند نشده |
| نگهداری آپدیت دریافتنشده | حداکثر ۲۴ ساعت | ۲۰۰۰ پیام آخر، به مدت ۲۴ ساعت |
| گزارش خطای تحویل | فیلد last_error_message در getWebhookInfo | فقط فیلد url |
تعریفها هر چه بگویند Webhook چیست، تحویل در عمل به گواهی TLS بند است. فرستنده پیش از تحویل حتی یک بایت، گواهی سرور شما را میسنجد. اگر نپذیرد، درخواست به برنامه نمیرسد و لاگ برنامه خالی میماند.
| حالت خرابی | چه میشکند | نشانه | رفع |
|---|---|---|---|
فایل cert.pem بهجای fullchain.pem | گواهی میانی به فرستنده نمیرسد | تلگرام: خطای آخرین تحویل در last_error_message؛ بله: فقط لاگ nginx | خط ssl_certificate روی fullchain.pem |
| گواهی self-signed برای ربات بله | بله پارامتر certificate ندارد | مستند نشده؛ با لاگ nginx بسنجید | گواهی Let’s Encrypt برای زیردامنه |
طبق مستندات Certbot، فایل cert.pem فقط گواهی سرور را دارد و fullchain.pem همه گواهیها را؛ nginx برای ssl_certificate همین دومی را لازم دارد.
پیشنیاز: رکورد DNS زیردامنه روی همین سرور، و یک بلوک server روی پورت 80 با server_name همان زیردامنه تا Certbot آن را پیدا کند. پلاگین nginx خطوط listen 443 ssl و ssl_certificate را خودش اضافه میکند. نصب خود Certbot در راهنمای نصب SSL رایگان Let’s Encrypt آمده است.
sudo certbot --nginx -d bot.example.com
sudo certbot renew --dry-run
sudo nginx -T | grep ssl_certificate
⚠️ گواهی self-signed و گواهی تاریخگذشته
تلگرام گواهی self-signed را فقط با پارامتر certificate میپذیرد و بله این پارامتر را ندارد؛ گواهی عمومی بگیرید.
✅ بعد از هر تمدید، getWebhookInfo یا لاگ nginx را ببینید؛ گواهی تاریخگذشته بیصدا تحویل را قطع میکند.

به زبان پیکربندی، Webhook چیست؟ یک location در nginx که فقط POST را به برنامهای روی 127.0.0.1 بدهد، و برنامهای که پیش از هر کار سنگین 200 برگرداند. تلگرام هر درخواستی را که جواب غیر 2xx بگیرد دوباره میفرستد، پس هر جواب خطا همان پیام را دوباره میآورد.
این location را به همان بلوک 443 که Certbot ساخته اضافه کنید. بلوک دوم با همان server_name نسازید.
server {
listen 443 ssl; # Certbot نوشته
server_name bot.example.com;
ssl_certificate /etc/letsencrypt/live/bot.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/bot.example.com/privkey.pem;
# مسیر: خروجی openssl rand -hex 24
location = /hook/3c9e1f7a5b2d8c4e6f0a1b3d5e7f9a2c4b6d8e0f1a3c5e7b {
limit_except POST { deny all; } # فقط POST
proxy_pass http://127.0.0.1:8081; # فقط localhost
proxy_set_header Host $host;
}
}
طبق صفحه ngx_http_proxy_module در مستندات nginx، بدون proxy_set_header، Host به $proxy_host بازنویسی میشود. proxy_read_timeout (پیشفرض ۶۰ ثانیه) فاصله مجاز nginx بین دو خواندن از برنامه است، نه صبر تلگرام؛ مهلت تلگرام و بله منتشر نشده است. بعد از هر تغییر، sudo nginx -t و سپس sudo nginx -s reload.
این گیرنده با کتابخانه استاندارد پایتون روی Python 3.13 امتحان شد. هدر را میسنجد، 200 میدهد و بدنه را به صف worker میسپارد. خطای هر آپدیت لاگ میشود و worker سر پا میماند.
import hmac, json, logging, os, queue, sqlite3, threading
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
SECRET = os.environ["WEBHOOK_SECRET"].encode()
jobs = queue.Queue()
class Hook(BaseHTTPRequestHandler):
def do_POST(self):
got = self.headers.get("X-Telegram-Bot-Api-Secret-Token", "").encode()
if not hmac.compare_digest(got, SECRET): # برای بله این دو خط را بردارید
self.send_response(403); self.end_headers(); return
body = self.rfile.read(int(self.headers.get("Content-Length", 0)))
self.send_response(200) # اول جواب
self.end_headers()
jobs.put(body) # بعد صف
def handle(update, db):
try:
with db:
db.execute("INSERT INTO seen VALUES (?)", (update["update_id"],))
except sqlite3.IntegrityError:
return # تکراری
print("new update", update["update_id"], flush=True) # منطق ربات شما
def worker():
db = sqlite3.connect("seen.db")
db.execute("CREATE TABLE IF NOT EXISTS seen (id INTEGER PRIMARY KEY)")
while True:
body = jobs.get()
try:
handle(json.loads(body), db)
except Exception:
logging.exception("update failed")
threading.Thread(target=worker, daemon=True).start()
ThreadingHTTPServer(("127.0.0.1", 8081), Hook).serve_forever()
کلید را در فایلی که فقط خودتان میخوانید بگذارید و هنگام اجرا به برنامه بدهید؛ در سرویس دائمی، از فایل محیطی سرویس.
openssl rand -hex 32 > ~/.webhook_secret && chmod 600 ~/.webhook_secret
WEBHOOK_SECRET=$(cat ~/.webhook_secret) python3 hook.py
⚠️ کار سنگین پیش از پاسخ، پیام تکراری میسازد
اتصال به API دیگر پیش از جواب، کندی آن سرویس را به پاسخ دیر تبدیل میکند. رفتار فرستنده با پاسخ دیر مستند نیست؛ تکرار محتمل است.
✅ صف این نمونه در حافظه است و با ریاستارت خالی میشود؛ برای پرداخت، صف را در دیتابیس نگه دارید.

در آموزشهای Webhook چیست کمتر کسی میگوید نشانی شما روی اینترنت باز است. هر کسی که آن را بداند، میتواند JSONی شبیه آپدیت تلگرام بفرستد. پس گیرنده دو سنجش لازم دارد: فرستنده همان سرویس باشد و رویداد تازه.
حسابدار فروشگاه چک را پیش از قبول در سامانه صیاد استعلام میکند و چکی را که وصول کرده، دوباره به بانک نمیبرد. گیرنده بالا هم اول هدر را میسنجد و بعد شناسه رویداد را با جدول seen.
در تلگرام، مقدار secret_token را هنگام setWebhook میدهید و تلگرام آن را در هدر X-Telegram-Bot-Api-Secret-Token هر درخواست میگذارد. طولش ۱ تا ۲۵۶ نویسه است، از حروف لاتین، رقم، زیرخط و خط تیره، که خروجی hex از openssl در آن میگنجد. ثبت برای هر دو پیامرسان:
read -rs BOT_TOKEN # بیرون از history
HOOK="https://bot.example.com/hook/<مسیر-تصادفی>"
# تلگرام
curl -s "https://api.telegram.org/bot$BOT_TOKEN/setWebhook" \
-d url="$HOOK" -d secret_token="$(cat ~/.webhook_secret)"
curl -s "https://api.telegram.org/bot$BOT_TOKEN/getWebhookInfo"
# بله: فقط url
curl -s "https://tapi.bale.ai/bot$BOT_TOKEN/setWebhook" -d url="$HOOK"
🔸 سنجش هدر در دو خط اول do_POST
این دو خط هدر را با hmac.compare_digest میسنجند. هر دو طرف bytes هستند تا هدر غیر ASCII خطا نسازد، و زمان مقایسه ثابت است.
بله این هدر را نمیفرستد. آنجا تنها چیزی که میماند خود مسیر است: بخشی تصادفی که با openssl rand -hex 24 میسازید و در مخزن کد نمیآورید. این حفاظت ضعیفتر است. هر جا نشانی ثبت شود، کلید هم ثبت شده است.
بعضی سرویسها بهجای هدر ثابت، کل بدنه را امضا میکنند. در مستندات GitHub، هدر X-Hub-Signature-256 مقدار HMAC-SHA256 بدنه با کلید مخفی شماست، به شکل hex و با پیشوند sha256=. HMAC را روی بایتهای خام بدنه و پیش از json.loads حساب کنید و بهجای == با روش زمانثابت بسنجید. نمونه زیر با بردار آزمون GitHub درست درآمد.
# بهجای دو خط سنجش هدر در do_POST، با import hashlib
body = self.rfile.read(int(self.headers.get("Content-Length", 0)))
expected = "sha256=" + hmac.new(SECRET, body, hashlib.sha256).hexdigest()
got = self.headers.get("X-Hub-Signature-256", "")
if not hmac.compare_digest(expected.encode(), got.encode()):
self.send_response(401); self.end_headers(); return
تلگرام update_id را برای نادیده گرفتن تکراریها معرفی میکند؛ در بله هم این شناسه از صفر و ترتیبی است. handle() آن را در ستون کلید یکتا مینویسد و تکراری با IntegrityError کنار میرود. ثبت پیش از پردازش است، پس آپدیت خطادار فقط در لاگ میماند. «بزرگتر از آخرین شناسه» ملاک نیست؛ تلگرام بعد از یک هفته بیآپدیتی شناسه را تصادفی میگذارد.
نشانی ثبت شده، setWebhook جواب true داده و لاگ nginx هنوز خالی است؟ جواب اول چهار مظنون را نام میبرد.
جواب true فقط یعنی نشانی پذیرفته شده است. DNS، پورت، فایروال و fullchain.pem را ببینید. در تلگرام، last_error_message خطای آخرین تحویل را میگوید؛ در بله فقط لاگ nginx شاهد است.
نه؛ مستندات بله فقط 443 و 88 را نام برده است. اگر 443 را سایت دیگری گرفته، ربات را با server_name جدا پشت همان nginx بگذارید.
سازوکار یکی است. روش تأیید درخواست را از مستندات همان درگاه بردارید و پیش از آن، سفارشی را پرداختشده علامت نزنید.
در تلگرام نه؛ تا وبهوک فعال است getUpdates چیزی نمیگیرد. بله در این باره چیزی ننوشته است؛ برای آزمایش محلی، اول وبهوک را بردارید.
پیش خود پیامرسان. تلگرام آپدیت دریافتنشده را حداکثر ۲۴ ساعت نگه میدارد و بله ۲۰۰۰ پیام آخر را به مدت ۲۴ ساعت؛ ربات پرپیام بله ممکن است از سقف ۲۰۰۰ بگذرد.
در هر دو پیامرسان setWebhook را با url خالی صدا بزنید. در تلگرام، drop_pending_updates آپدیتهای مانده را هم دور میریزد.
اگر برنامه و تلگرام همزمان عوض نشوند، آپدیت واقعی 403 میگیرد. مدتی هر دو مقدار را بپذیرید و بعد قدیمی را حذف کنید.
جمعبندی؛ Webhook چیست از نگاه سروری که درخواست را میگیرد گیرنده سالم گواهی را با fullchain.pem سرو میکند و تمدیدش را با certbot renew --dry-run آزموده است. روی پورتی گوش میدهد که پیامرسان میشناسد؛ برای بله یعنی 443 یا 88. پیش از هر کار سنگین 200 برمیگرداند و کار را به صفی میدهد که با یک خطا نمیمیرد. هر درخواست را دو بار میسنجد: برای فرستنده با هدر مخفی یا امضای HMAC، و برای تکرار با update_id. در بله، مسیر تصادفی تنها حفاظت است. جا افتادن هر کدام خطایی روی صفحه نمیاندازد؛ فقط پیامی نمیرسد، یا سفارشی دو بار ثبت میشود.
🚀 برنامهای که پشت این نشانی مینشیند
پیش از ثبت نشانی، بسنجید ربات شما اصلاً وبهوک میخواهد یا Polling بس است؛ راهنمای رباتهای بله، روبیکا و ایتا همین را کنار سرویس systemd میگذارد.
چه سرویسی پشت نشانی وبهوک شماست؟ اولین خرابیاش را با شماره ردیف جدول اول گزارش کنید؛ اگر در هیچ ردیفی جا نشد، همان برای ما خبر است.
منابع