Webhook

В webhook-режиме сервер сам шлёт обновления на ваш URL вместо того, чтобы вы их забирали через getUpdates.

Установка webhook

curl -X POST https://api.telefon.chat/bot<TOKEN>/setWebhook \
  -d 'url=https://your-server.com/webhook'

Параметры:

• url — обязательный, должен быть HTTPS.
• certificate — самоподписанный сертификат (необязательно, если HTTPS валиден).
• max_connections — лимит одновременных соединений (1–100, default 40).
• allowed_updates — список типов обновлений; остальные не шлются.
• drop_pending_updates — сбросить очередь старых обновлений.
• secret_token — необязательный секрет, передаётся в заголовке X-Telefon-Bot-Api-Secret-Token.

Формат входящего запроса

POST /webhook HTTP/1.1
Host: your-server.com
Content-Type: application/json
X-Telefon-Bot-Api-Secret-Token: ваш-секрет

{
  "update_id": 123456,
  "message": {
    "message_id": 42,
    "from": {"id": 999, "first_name": "Иван"},
    "chat": {"id": 12345, "type": "private"},
    "date": 1714326600,
    "text": "/start"
  }
}

Ответ должен быть 200 OK в течение 60 сек. Если 5xx или таймаут — сервер повторит позже.

Подпись (signature)

Помимо secret_token, мы шлём подпись HMAC-SHA256 в заголовке X-Telefon-Signature. Проверка:

import hmac, hashlib

def verify(body_bytes, signature, secret):
    expected = hmac.new(secret.encode(), body_bytes, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Получение информации

curl https://api.telefon.chat/bot<TOKEN>/getWebhookInfo

Ответ:

{
  "ok": true,
  "result": {
    "url": "https://your-server.com/webhook",
    "has_custom_certificate": false,
    "pending_update_count": 0,
    "last_error_date": null,
    "last_error_message": null,
    "max_connections": 40
  }
}

Снятие webhook

curl https://api.telefon.chat/bot<TOKEN>/deleteWebhook

После этого можно снова использовать getUpdates.

Совет: idempotency

Иногда мы можем доставить одно и то же обновление дважды (например, при таймауте ответа). Сохраняйте update_id обработанных событий и игнорируйте дубли:

processed = set()

def handle(update):
    if update['update_id'] in processed:
        return
    processed.add(update['update_id'])
    # ... обработка

Ограничения

• URL должен быть HTTPS.
• Размер запроса до 10 МБ.
• 60 сек на ответ.
• Webhook не работает на 127.0.0.1 — используйте ngrok/cloudflared для локальной разработки.