From e37eddbe8c6fccfdfa49fdd249e7ebadc511d6c5 Mon Sep 17 00:00:00 2001
From: Kostiantyn Kriuchkov <36363097+Latand@users.noreply.github.com>
Date: Sun, 15 Feb 2026 20:24:15 +0200
Subject: [PATCH] Document webhook proxy trust model (#47) (#1765)

---
 CHANGES/47.misc.rst                           |  1 +
 docs/dispatcher/webhook.rst                   | 13 +++++
 .../uk_UA/LC_MESSAGES/dispatcher/webhook.po   | 58 +++++++++++++++++--
 3 files changed, 68 insertions(+), 4 deletions(-)
 create mode 100644 CHANGES/47.misc.rst

diff --git a/CHANGES/47.misc.rst b/CHANGES/47.misc.rst
new file mode 100644
index 00000000..c895c16f
--- /dev/null
+++ b/CHANGES/47.misc.rst
@@ -0,0 +1 @@
+Documented webhook security constraints for proxy deployments, including trust requirements for :code:`X-Forwarded-For` and recommended defense-in-depth checks.
diff --git a/docs/dispatcher/webhook.rst b/docs/dispatcher/webhook.rst
index 73bcddbc..26c58f36 100644
--- a/docs/dispatcher/webhook.rst
+++ b/docs/dispatcher/webhook.rst
@@ -66,6 +66,19 @@ It can be acy using firewall rules or nginx configuration or middleware on appli
 
 So, aiogram has an implementation of the IP filtering middleware for aiohttp.
 
+`aiogram` IP filtering middleware reads the left-most IP address from `X-Forwarded-For`.
+
+.. warning::
+
+    `X-Forwarded-For` is trustworthy only if all webhook traffic goes through a trusted reverse proxy that rewrites this header.
+    If your application is directly reachable from the Internet, this header can be forged.
+
+For production deployments, use defense in depth:
+
+- Always set and verify :code:`X-Telegram-Bot-Api-Secret-Token`
+- Restrict network access to the webhook endpoint (firewall, security groups, ACL)
+- Ensure the backend app is not publicly reachable and accepts requests only from the trusted proxy
+
 .. autofunction:: aiogram.webhook.aiohttp_server.ip_filter_middleware
 
 .. autoclass:: aiogram.webhook.security.IPFilter
diff --git a/docs/locale/uk_UA/LC_MESSAGES/dispatcher/webhook.po b/docs/locale/uk_UA/LC_MESSAGES/dispatcher/webhook.po
index 880fef46..ee10e8ca 100644
--- a/docs/locale/uk_UA/LC_MESSAGES/dispatcher/webhook.po
+++ b/docs/locale/uk_UA/LC_MESSAGES/dispatcher/webhook.po
@@ -203,45 +203,95 @@ msgstr ""
 
 #: ../../dispatcher/webhook.rst:51
 msgid "Security"
-msgstr ""
+msgstr "Безпека"
 
 #: ../../dispatcher/webhook.rst:53
 msgid ""
 "Telegram supports two methods to verify incoming requests that they are "
 "from Telegram:"
-msgstr ""
+msgstr "Telegram підтримує два методи перевірки вхідних запитів, що вони надходять від Telegram:"
 
 #: ../../dispatcher/webhook.rst:56
 msgid "Using a secret token"
-msgstr ""
+msgstr "Використання секретного токена"
 
 #: ../../dispatcher/webhook.rst:58
 msgid ""
 "When you set webhook, you can specify a secret token and then use it to "
 "verify incoming requests."
 msgstr ""
+"Коли ви налаштовуєте webhook, ви можете вказати секретний токен і потім "
+"використовувати його для перевірки вхідних запитів."
 
 #: ../../dispatcher/webhook.rst:61
 msgid "Using IP filtering"
-msgstr ""
+msgstr "Використання фільтрації за IP"
 
 #: ../../dispatcher/webhook.rst:63
 msgid ""
 "You can specify a list of IP addresses from which you expect incoming "
 "requests, and then use it to verify incoming requests."
 msgstr ""
+"Ви можете вказати список IP-адрес, з яких очікуєте вхідні запити, і "
+"використовувати його для перевірки запитів."
 
 #: ../../dispatcher/webhook.rst:65
 msgid ""
 "It can be acy using firewall rules or nginx configuration or middleware "
 "on application level."
 msgstr ""
+"Це можна зробити за допомогою правил firewall, конфігурації nginx або "
+"middleware на рівні застосунку."
 
 #: ../../dispatcher/webhook.rst:67
 msgid ""
 "So, aiogram has an implementation of the IP filtering middleware for "
 "aiohttp."
 msgstr ""
+"Тому в aiogram є реалізація middleware для фільтрації за IP для aiohttp."
+
+#: ../../dispatcher/webhook.rst:69
+msgid ""
+"`aiogram` IP filtering middleware reads the left-most IP address from "
+"`X-Forwarded-For`."
+msgstr ""
+"IP-фільтр middleware в `aiogram` читає крайню ліву IP-адресу з "
+"`X-Forwarded-For`."
+
+#: ../../dispatcher/webhook.rst:73
+msgid ""
+"`X-Forwarded-For` is trustworthy only if all webhook traffic goes through a"
+" trusted reverse proxy that rewrites this header. If your application is "
+"directly reachable from the Internet, this header can be forged."
+msgstr ""
+"`X-Forwarded-For` можна вважати надійним лише тоді, коли весь webhook-"
+"трафік проходить через довірений reverse proxy, який перезаписує цей "
+"заголовок. Якщо ваш застосунок напряму доступний з Інтернету, цей "
+"заголовок можна підробити."
+
+#: ../../dispatcher/webhook.rst:76
+msgid "For production deployments, use defense in depth:"
+msgstr "Для production-деплойментів використовуйте багаторівневий захист:"
+
+#: ../../dispatcher/webhook.rst:78
+msgid "Always set and verify :code:`X-Telegram-Bot-Api-Secret-Token`"
+msgstr "Завжди встановлюйте та перевіряйте :code:`X-Telegram-Bot-Api-Secret-Token`"
+
+#: ../../dispatcher/webhook.rst:79
+msgid ""
+"Restrict network access to the webhook endpoint (firewall, security "
+"groups, ACL)"
+msgstr ""
+"Обмежуйте мережевий доступ до webhook endpoint (firewall, security groups, "
+"ACL)"
+
+#: ../../dispatcher/webhook.rst:80
+msgid ""
+"Ensure the backend app is not publicly reachable and accepts requests only "
+"from the trusted proxy"
+msgstr ""
+"Переконайтеся, що backend-застосунок не доступний публічно та приймає "
+"запити лише від довіреного proxy"
 
 #: ../../dispatcher/webhook.rst:75
 msgid "Examples"