تصور رایج این است که وب‌هوک فقط یک نشانی در تنظیمات سرویس است. این تصور فقط از سمت فرستنده می‌گوید 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 رد شوند یا دو بار بیایند. برنامه‌ای که این درخواست‌ها را تحویل می‌گیرد، روی همان سروری می‌نشیند که میزبانی ربات بله آماده‌اش کرده است.

webhook چیست، نمودار مسیر درخواست HTTPS از سرور پیام‌رسان تا nginx و صف پردازش روی سرور

وب‌هوک یعنی سرور شما شنونده است

با کاری که Webhook جایش را می‌گیرد، یعنی دریافت دوره‌ای (Polling)، راحت‌تر می‌شود فهمید Webhook چیست. آن‌جا برنامه خودش مدام سراغ API می‌رود. در وب‌هوک جهت برعکس است: پیام‌رسان یا درگاه رویداد را خودش به نشانی شما POST می‌کند.

تلگرام و بله در ثبت وب‌هوک یکسان نیستند

نام متدهای بله همان نام‌های Bot API تلگرام است، ولی پارامترها و پورت‌ها نه. جدول زیر از مستندات رسمی هر دو در آبان ۱۴۰۵ است: Bot API تلگرام و مستندات بازوی بله.

موردتلگرامبله
نشانی متدهاhttps://api.telegram.org/bot<token>/METHOD_NAMEhttps://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، 8443443 و 88
هدر مخفیX-Telegram-Bot-Api-Secret-Tokenمستند نشده
تکرار ارسال ناموفقبرای پاسخ غیر 2xx، تا «تعداد معقولی» تلاشمستند نشده
نگه‌داری آپدیت دریافت‌نشدهحداکثر ۲۴ ساعت۲۰۰۰ پیام آخر، به مدت ۲۴ ساعت
گزارش خطای تحویلفیلد last_error_message در getWebhookInfoفقط فیلد url

پیش‌نیاز دامنه و SSL؛ خطاهایی که تحویل را قطع می‌کنند

تعریف‌ها هر چه بگویند 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 همین دومی را لازم دارد.

گرفتن گواهی با Certbot برای زیردامنه ربات

پیش‌نیاز: رکورد 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 را ببینید؛ گواهی تاریخ‌گذشته بی‌صدا تحویل را قطع می‌کند.

پیش‌نیاز دامنه و SSL؛ خطاهایی که تحویل را قطع می‌کنند

دریافت درخواست با Nginx و پاسخ سریع

به زبان پیکربندی، Webhook چیست؟ یک location در nginx که فقط POST را به برنامه‌ای روی 127.0.0.1 بدهد، و برنامه‌ای که پیش از هر کار سنگین 200 برگرداند. تلگرام هر درخواستی را که جواب غیر 2xx بگیرد دوباره می‌فرستد، پس هر جواب خطا همان پیام را دوباره می‌آورد.

بلوک location با حاشیه‌نویسی

این 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 می‌سازید و در مخزن کد نمی‌آورید. این حفاظت ضعیف‌تر است. هر جا نشانی ثبت شود، کلید هم ثبت شده است.

امضای HMAC؛ الگویی برای درگاه‌ها و سرویس‌های دیگر

بعضی سرویس‌ها به‌جای هدر ثابت، کل بدنه را امضا می‌کنند. در مستندات 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 هنوز خالی است؟ جواب اول چهار مظنون را نام می‌برد.

چرا setWebhook موفق است ولی هیچ درخواستی به سرور نمی‌رسد؟

جواب 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 می‌گذارد.

چه سرویسی پشت نشانی وب‌هوک شماست؟ اولین خرابی‌اش را با شماره ردیف جدول اول گزارش کنید؛ اگر در هیچ ردیفی جا نشد، همان برای ما خبر است.

منابع

وب داده
وب داده

جدید ترین مطالب آموزشی و کاربردی را در اینجا بخوانید !
ما با بهره‌گیری از دانش روز و تجربه متخصصان حوزه فناوری، مجموعه‌ای از آموزش‌های کاربردی و مقالات تخصصی را گردآوری کرده‌ایم که هر یک، پاسخی دقیق به پرسش‌های شماست. ؛ از مفاهیم پایه تا پیچیده‌ترین تکنیک‌های حرفه‌ای. اینجا، دانش با زبانی ساده اما عمیق در اختیار شما قرار می‌گیرد.

مقاله‌ها: 302
پاسخی بگذارید

نشانی ایمیل شما منتشر نخواهد شد. بخش‌های موردنیاز علامت‌گذاری شده‌اند *