پرش به محتویات

دریافت رویدادها با وب‌هوک (Webhooks)

برای محیط‌های عملیاتی و پروداکشن با ترافیک بالا، استفاده از Webhooks سریع‌ترین و بهینه‌ترین روش دریافت رویدادهاست. سرور کدمیت به محض رخ دادن هر رویداد، یک درخواست POST حاوی آبجکت JSON آپدیت به آدرس URL سرور شما ارسال می‌کند.

الزامات امنیتی وب‌هوک

  1. پروتکل HTTPS معتبر: آدرس سرور وب‌هوک حتماً باید دارای گواهی معتبر TLS/SSL (مانند Let's Encrypt) باشد.
  2. پورت‌های استاندارد: پورت‌های ۴۴۳، ۸۰، ۸۰۸۰ یا ۸۴۴۳ توصیه می‌شوند.
  3. توکن مخفی (Secret Token): برای اطمینان از اینکه درخواست‌ها واقعاً از سرور کدمیت ارسال شده‌اند، یک توکن تصادفی در هدر اعتبارسنجی تنظیم کنید.

متدهای مدیریت وب‌هوک

۱. تنظیم وب‌هوک (setWebhook)

با فراخوانی این متد، وب‌هوک برای ربات شما فعال می‌شود:

POST https://botapi.codemeet.chat/bot<TOKEN>/setWebhook

پارامترهای ورودی

پارامتر نوع وضعیت توضیحات
url String اجباری آدرس HTTPS عمومی برای دریافت درخواست‌های POST (مثال: https://mybot.example.com/webhook).
secret_token String اختیاری رشته‌ای بین ۱ تا ۲۵۶ کاراکتر (فقط A-Z, a-z, 0-9, _ و -). در هر درخواست به عنوان هدر ارسال می‌شود.
drop_pending_updates Boolean اختیاری اگر true باشد، تمام پیام‌های تحویل‌نشده قبلی پاک می‌شوند تا پیام‌های قدیمی تکرار نشوند.
max_connections Integer اختیاری حداکثر اتصالات همزمان (بین ۱ تا ۱۰۰، پیش‌فرض: ۴۰).
allowed_updates Array of String اختیاری لیست نوع آپدیت‌های مجاز.

نمونه درخواست تنظیم وب‌هوک

{
  "url": "https://api.example.com/codemeet/webhook",
  "secret_token": "a8fbc7190d3e21849102cba",
  "drop_pending_updates": true
}

نمونه پاسخ

{
  "ok": true,
  "result": true
}

۲. بررسی وضعیت وب‌هوک (getWebhookInfo)

برای مشاهده وضعیت اتصال وب‌هوک، خطاهای احتمالی اخیر و تعداد پیام‌های در صف انتظار:

GET POST https://botapi.codemeet.chat/bot<TOKEN>/getWebhookInfo

نمونه پاسخ

{
  "ok": true,
  "result": {
    "url": "https://api.example.com/codemeet/webhook",
    "has_custom_certificate": false,
    "pending_update_count": 0,
    "last_error": null
  }
}

۳. حذف وب‌هوک (deleteWebhook)

برای غیرفعال کردن وب‌هوک و بازگشت به روش Long Polling:

POST https://botapi.codemeet.chat/bot<TOKEN>/deleteWebhook 
{
  "drop_pending_updates": false
}

نمونه پیاده‌سازی سرور وب‌هوک با FastAPI (Python)

from fastapi import FastAPI, Request, Header, HTTPException

app = FastAPI()

BOT_TOKEN = "YOUR_BOT_TOKEN"
WEBHOOK_SECRET = "a8fbc7190d3e21849102cba"

@app.post("/webhook")
async def receive_update(
    request: Request,
    x_codemeet_bot_api_secret_token: str | None = Header(None)
):
    update = await request.json()
    print("Received Update:", update)

    if "message" in update:
        msg = update["message"]
        chat_id = msg["chat"]["id"]
        text = msg.get("text", "")
        # پردازش پیام و ارسال پاسخ...

    return {"status": "ok"}