Как работает прокси-вебхук

Прокси MaxBotStat — это HTTPS-эндпоинт вида https://capybara.maxbotstat.ru/proxy/<botId>/<secret>. На него Telegram (или Max) отправляет webhook, MaxBotStat:

1. сверяет <secret> — должен совпадать с proxy_secret бота из БД;
2. парсит апдейт и сохраняет:
   • контакт (или обновляет last_seen_at),
   • сообщение (direction='in'),
   • источник (если в /start есть utm_source-параметр),
   • intent (если попадает в правила автокатегоризации);
3. если у бота указан target_url — пересылает оригинальный JSON туда без изменений;
4. возвращает 200 OK Telegram/Max.

┌──────────────┐     POST /proxy/<id>/<secret>     ┌──────────────────┐     POST <target_url>     ┌────────────┐
│  Telegram /  │ ───────────────────────────────► │   MaxBotStat     │ ────────────────────────► │ Ваш backend │
│     Max      │                                   │ (сохраняет всё)  │                           │             │
└──────────────┘                                   └──────────────────┘                           └────────────┘

Формат запроса

Telegram и Max шлют свои стандартные JSON. MaxBotStat ничего не меняет в payload — ваш backend получает то же самое, что прислал бы Telegram напрямую.

Пример апдейта Telegram, прошедшего через прокси:

{
  "update_id": 100000001,
  "message": {
    "message_id": 42,
    "from": {
      "id": 123456789,
      "is_bot": false,
      "first_name": "Анна",
      "username": "anna",
      "language_code": "ru"
    },
    "chat": {
      "id": 123456789,
      "first_name": "Анна",
      "username": "anna",
      "type": "private"
    },
    "date": 1735689600,
    "text": "/start utm_source=instagram"
  }
}

В этот же момент в кабинете появляется:

• контакт 123456789 с username anna;
• сообщение "/start utm_source=instagram" в направлении in;
• запись в bot_contact_attribution с source_value="instagram".

Безопасность

• proxy_secret — 24 hex-символа (12 случайных байт). Угадать перебором нереально.
• Неверный proxy_secret → ответ 404. Лог не пишется, поэтому подбор не оставляет следов в аналитике, но и не даёт данных.
• Все запросы идут по HTTPS (Let's Encrypt сертификат).
• Если вы подозреваете, что URL утёк — удалите бота и подключите заново. proxy_secret сгенерируется заново.

Что MaxBotStat сохраняет

Сущность	Поля
contacts	external_user_id, username, first_name, last_name, is_premium, phone, last_seen_at, source_value, campaign_name
messages	direction (in/out), text, raw_json, created_at, external_user_id
media (опц.)	kind (photo/audio/file), file_id, mime_type, size_bytes
intents (если настроены)	связь сообщения с intent'ом

raw_json — полная исходная нагрузка от Telegram/Max. Полезно для дебага и для своих интеграций.

Поведение при недоступности target_url

• Если ваш backend ответил 5xx, MaxBotStat не повторяет запрос — Telegram сам ретраит до 24 часов.
• Если backend ответил 2xx, MaxBotStat возвращает 200 OK Telegram, и тот считает апдейт доставленным.
• Если target_url=polling, MaxBotStat возвращает 200 OK сразу.

TIP

Не надо «писать собственный прокси». Установка webhook'а на https://capybara.maxbotstat.ru/proxy/... работает с любым backend на любом языке.

Переход на новый домен или сервер

При смене вашего backend просто обновите target_url в карточке бота — webhook бота не меняется, Telegram не нужно перенастраивать.