{"id":35131194,"url":"https://github.com/m-xim/aiogram-webhook","last_synced_at":"2026-02-21T21:21:25.763Z","repository":{"id":331000498,"uuid":"1123898793","full_name":"m-xim/aiogram-webhook","owner":"m-xim","description":"Python library for seamless webhook integration with multiple web frameworks in aiogram. It enables both single and multi-bot operation via webhooks, with flexible routing and security features.","archived":false,"fork":false,"pushed_at":"2025-12-29T18:41:41.000Z","size":28,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-01T21:20:52.431Z","etag":null,"topics":["aiogram","aiogram-bot","aiogram-webhooks","aiogram3-fastapi","aiogram3-webhooks","aiohttp","fastapi","multibot","telegram","webhook"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/aiogram-webhook","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/m-xim.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-27T21:46:25.000Z","updated_at":"2025-12-29T18:41:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/m-xim/aiogram-webhook","commit_stats":null,"previous_names":["m-xim/aiogram-webhook"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/m-xim/aiogram-webhook","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m-xim%2Faiogram-webhook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m-xim%2Faiogram-webhook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m-xim%2Faiogram-webhook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m-xim%2Faiogram-webhook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/m-xim","download_url":"https://codeload.github.com/m-xim/aiogram-webhook/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m-xim%2Faiogram-webhook/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28400463,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aiogram","aiogram-bot","aiogram-webhooks","aiogram3-fastapi","aiogram3-webhooks","aiohttp","fastapi","multibot","telegram","webhook"],"created_at":"2025-12-28T05:14:32.598Z","updated_at":"2026-02-15T17:40:28.090Z","avatar_url":"https://github.com/m-xim.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# aiogram-webhook\n\n[![PyPI version](https://img.shields.io/pypi/v/aiogram-webhook?color=blue)](https://pypi.org/project/aiogram-webhook)\n[![License](https://img.shields.io/github/license/m-xim/aiogram-webhook.svg)](/LICENSE)\n[![Tests Status](https://github.com/m-xim/aiogram-webhook/actions/workflows/tests.yml/badge.svg)](https://github.com/m-xim/aiogram-webhook/actions)\n[![Release Status](https://github.com/m-xim/aiogram-webhook/actions/workflows/release.yml/badge.svg)](https://github.com/m-xim/aiogram-webhook/actions)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/m-xim/aiogram-webhook)\n\n**aiogram-webhook** is a modular Python library for seamless webhook integration with multiple web frameworks in aiogram. It enables both single and multi-bot operation via webhooks, with flexible routing and security features.\n\n---\n\n## ✨ Features\n\n- 🧱 Modular and extensible webhook engine\n- 🔀 Flexible routing (static, tokenized, custom)\n- 🤖 Single-bot and multi-bot support\n- ⚡ Adapters for FastAPI and aiohttp\n- 🔒 Security: secret tokens, IP checks, custom security\n- 🧩 Easily extendable with your own adapters, routing, and security\n\n---\n\n## 🚀 Installation\n\n```bash\nuv add aiogram-webhook\n# or\npip install aiogram-webhook\n```\n\n---\n\n## ⚡ Quick Start\n\n### FastAPI\n```python\nfrom contextlib import asynccontextmanager\nfrom fastapi import FastAPI\nfrom aiogram import Bot, Dispatcher, Router\nfrom aiogram.filters import CommandStart\nfrom aiogram.types import Message\nfrom aiogram_webhook import SimpleEngine, FastApiWebAdapter, WebhookConfig\nfrom aiogram_webhook.routing import StaticRouting\n\nrouter = Router()\n\n\n@router.message(CommandStart())\nasync def start(message: Message):\n    await message.answer(\"OK\")\n\n\ndispatcher = Dispatcher()\ndispatcher.include_router(router)\nbot = Bot(\"BOT_TOKEN\")\n\n\nengine = SimpleEngine(\n    dispatcher,\n    bot,\n    web_adapter=FastApiWebAdapter(),\n    routing=StaticRouting(url=\"https://example.com/webhook\"),\n    webhook_config=WebhookConfig(allowed_updates=[\"message\", \"callback_query\"], drop_pending_updates=True),\n    # security=Security(...)\n)\n\n\n@asynccontextmanager\nasync def lifespan(app: FastAPI):\n    engine.register(app)\n    await engine.set_webhook()  # Uses webhook_config defaults\n    # Or override specific params:\n    # await engine.set_webhook(max_connections=100)\n    await engine.on_startup(app)\n    yield\n    await engine.on_shutdown(app)\n\n\napp = FastAPI(lifespan=lifespan)\n```\n\n### Aiohttp\n```python\nfrom aiogram import Bot, Dispatcher, Router\nfrom aiogram.filters import CommandStart\nfrom aiogram.types import Message\nfrom aiogram_webhook import SimpleEngine, AiohttpWebAdapter, WebhookConfig\nfrom aiogram_webhook.routing import StaticRouting\nfrom aiohttp import web\n\nrouter = Router()\n\n\n@router.message(CommandStart())\nasync def start(message: Message):\n    await message.answer(\"OK\")\n\n\nasync def on_startup(bot: Bot, webhook_engine: SimpleEngine) -\u003e None:\n    await webhook_engine.set_webhook()\n\n\ndispatcher = Dispatcher()\ndispatcher.include_router(router)\ndispatcher.startup.register(on_startup)\nbot = Bot(\"BOT_TOKEN\")\n\nengine = SimpleEngine(\n    dispatcher,\n    bot,\n    web_adapter=AiohttpWebAdapter(),\n    routing=StaticRouting(url=\"https://example.com/webhook\"),\n    webhook_config=WebhookConfig(allowed_updates=[\"message\", \"callback_query\"]),\n    # security=Security(...)\n)\napp = web.Application()\nengine.register(app)\n```\n\n---\n\n## 🧩 Engines\n\nIn aiogram-webhook, there are two main engines for integrating Telegram bots via webhook:\n\n#### SimpleEngine (Single-bot)\n\nUsed for serving a single Telegram bot. Suitable for most standard scenarios when you need to integrate only one bot with your application.\n\n- Connects aiogram `Dispatcher` and `Bot` to the selected web framework (FastAPI, aiohttp, etc.)\n- Handles webhook requests for a single bot\n- Requires explicit dispatcher, bot, web_adapter, and routing (security and webhook_config are optional)\n\n**Example:**\n```python\nfrom aiogram import Bot, Dispatcher\nfrom aiogram_webhook import SimpleEngine, FastApiWebAdapter, WebhookConfig\nfrom aiogram_webhook.routing import StaticRouting\n\nbot = Bot(\"BOT_TOKEN\")\ndispatcher = Dispatcher()\n\nengine = SimpleEngine(\n    dispatcher,\n    bot,\n    web_adapter=FastApiWebAdapter(),\n    routing=StaticRouting(url=\"https://example.com/webhook\"),\n    webhook_config=WebhookConfig(allowed_updates=[\"message\", \"callback_query\"], drop_pending_updates=True),\n    # security=Security(...)\n)\n```\n\n#### TokenEngine (Multi-bot)\n\nAllows you to serve multiple Telegram bots in a single application. Useful if you need to dynamically determine which bot the request is for (e.g., by token in the URL).\n\n- Allows serving multiple bots via a single endpoint\n- Uses the bot token for request routing\n- Requires dispatcher, web_adapter, routing, bot_settings (optional), webhook_config (optional), and security (optional)\n\n**Example:**\n\n```python\nfrom aiogram import Dispatcher, Router\nfrom aiogram.client.default import DefaultBotProperties\nfrom aiogram.types import Message\nfrom aiogram.filters import Command, CommandObject\nfrom aiogram_webhook import TokenEngine, FastApiWebAdapter, WebhookConfig\nfrom aiogram_webhook.routing import PathRouting\n\nrouter = Router()\n\n\n@router.message(Command(\"addbot\"))\nasync def add_bot_handler(message: Message, command: CommandObject, webhook_engine: TokenEngine):\n    token = command.args\n    if not token:\n        await message.answer(\"Use: /addbot \u003cTOKEN\u003e\")\n        return\n    new_bot = await webhook_engine.set_webhook(token)\n    await message.answer(f\"Bot #{new_bot.id} started!\")\n\n\ndispatcher = Dispatcher()\ndispatcher.include_router(router)\n\n\nengine = TokenEngine(\n    dispatcher,\n    web_adapter=FastApiWebAdapter(),\n    routing=PathRouting(url=\"https://example.com/webhook/{bot_token}\"),\n    bot_settings={\"default\": DefaultBotProperties(parse_mode=\"HTML\")},\n    webhook_config=WebhookConfig(allowed_updates=[\"message\", \"callback_query\"]),\n    # security=Security(...)\n)\n```\n\n#### Custom Engines\n\nYou can create your own engine by inheriting from the base engine class (`BaseEngine`). This allows you to implement custom logic for webhook processing, routing, or bot management.\n\n---\n\n## 🔌 Adapters: FastAPI and aiohttp\n\nAdapters connect the engine to your web framework.\n\n### FastAPI Adapter\n- Use `FastApiWebAdapter`\n- Register engine in FastAPI lifespan (see Quick Start)\n\n### Aiohttp Adapter\n- Use `AiohttpWebAdapter`\n- Just call `engine.register(app)`\n\n---\n\n## 🛣️ Routing\n\naiogram-webhook provides several routing strategies to determine webhook URLs and extract bot tokens from requests:\n\n### BaseRouting (Abstract)\nBase class for all routing strategies. Defines the webhook URL template and provides the interface for extracting information from requests.\n\n### StaticRouting (Single-bot)\nUsed with **SimpleEngine** for static webhook URLs without token extraction.\n- Returns the webhook URL as-is\n- No parameter extraction needed\n- Example: `https://example.com/webhook`\n\n```python\nfrom aiogram_webhook.routing import StaticRouting\n\nrouting = StaticRouting(url=\"https://example.com/webhook\")\n```\n\n### TokenRouting (Multi-bot, Abstract)\nBase class for token-based routing strategies. Used with **TokenEngine** to serve multiple bots.\n- Requires a URL template with a parameter placeholder (e.g. `{bot_token}`)\n- Extracts bot token from incoming requests\n- Automatically formats webhook URL using the bot token\n\n### PathRouting (Multi-bot)\nExtracts bot token from the URL path parameter.\n- Parameter is read from the path segment\n- Example: `https://example.com/webhook/123:ABC` → token extracted from path\n- Default parameter name: `\"bot_token\"`\n\n```python\nfrom aiogram_webhook.routing import PathRouting\n\n# Using default parameter name \"bot_token\"\nrouting = PathRouting(url=\"https://example.com/webhook/{bot_token}\")\n\n# Or with custom parameter name\nrouting = PathRouting(url=\"https://example.com/webhook/{token}\", param=\"token\")\n```\n\n### QueryRouting (Multi-bot)\nExtracts bot token from URL query parameters.\n- Parameter is read from the query string\n- Example: `https://example.com/webhook?token=123:ABC` → token extracted from query\n- Default parameter name: `\"bot_token\"`\n\n```python\nfrom aiogram_webhook.routing import QueryRouting\n\n# Using default parameter name \"bot_token\"\nrouting = QueryRouting(url=\"https://example.com/webhook\")\n\n# Or with custom parameter name\nrouting = QueryRouting(url=\"https://example.com/webhook\", param=\"token\")\n\n# Or with other parameters\nrouting = QueryRouting(url=\"https://example.com/webhook?other=value\")\n```\n\n### Custom Routing\nYou can implement your own routing by inheriting from `BaseRouting` or `TokenRouting` and implementing the `webhook_point()` method (and `extract_token()` if using token-based routing).\n\nSee [routing examples](/src/aiogram_webhook/routing) for implementation details.\n\n---\n\n## ⚙️ Webhook Configuration\n\n`WebhookConfig` allows you to set default parameters for the Telegram [`setWebhook`](https://core.telegram.org/bots/api#setwebhook) API call. All parameters are optional and can be overridden when calling `engine.set_webhook()`.\n\n---\n\n## 🛡️ Security\n\naiogram-webhook provides a flexible and extensible security system for processing webhook requests. You can use built-in mechanisms, combine them, or implement your own checks.\n\n```python\nfrom aiogram_webhook.security import Security, StaticSecretToken, IPCheck\n\nsecurity = Security(\n    IPCheck(),  # and other checks...\n    secret_token=StaticSecretToken(\"YOUR_SECRET_TOKEN\"),\n)\n```\n\n### Main features\n\n- **SecretToken** — verification of the Telegram secret token (e.g., via the `X-Telegram-Bot-Api-Secret-Token` header).\n- **IPCheck** — validation of the request source IP address (by default, official Telegram networks are supported, you can add your own addresses/networks).\n- **Combining checks** — you can combine several checks (for example, SecretToken and IPCheck simultaneously).\n- **Custom checks** — the ability to implement your own verification logic (e.g., by headers, parameters, etc.).\n\n### Using SecretToken\n\n```python\nfrom aiogram_webhook.security import Security, StaticSecretToken\n\nsecurity = Security(secret_token=StaticSecretToken(\"SECRET_TOKEN\"))\n```\n**StaticSecretToken** is a simple implementation of the `SecretToken` protocol that checks the provided token against a static value.\n\n#### Creating your own SecretToken (e.g., dynamic)\nYou can implement your own class based on the `SecretToken` protocol. For example, you may want to:\n- Store tokens in a database or environment variable\n- Use different tokens for different bots\n- Rotate tokens dynamically\n\n### Using IPCheck\n\n`IPCheck` is a security check that validates the client's IP address against allowed networks and addresses. It helps ensure that only requests from trusted sources (such as official Telegram servers or your own networks) are accepted.\n\n**Constructor parameters:**\n- `*ip_entries`: Any number of IP addresses or networks (as strings or ipaddress objects) to allow. You can specify both IPv4 and IPv6 addresses or networks.\n- `include_default` (bool, default: True): If True, includes the official Telegram IP networks in the allowed list. If False, only your custom addresses/networks will be used.\n\nYou can combine as many addresses and networks as needed. The check supports both IPv4 and IPv6.\n\n**Features:**\n- Automatic detection of client IP from direct connection or `X-Forwarded-For` header (for reverse proxy scenarios)\n- Works seamlessly with load balancers and reverse proxies\n\n**Example:**\n```python\nfrom aiogram_webhook.security import Security, IPCheck\n\n# Use default Telegram IP networks\nsecurity = Security(IPCheck())\n\n# Add custom addresses/networks\nsecurity = Security(IPCheck(\"192.168.1.0/24\", \"10.0.0.1\"))\n\n# Disable default Telegram networks and use only custom ones\nsecurity = Security(IPCheck(\"192.168.1.0/24\", include_default=False))\n```\n\n### Using a custom check\nYou can create your own security check by implementing the `SecurityCheck` protocol. This allows you to define custom logic for validating incoming requests based on your specific requirements.\nSee [checks examples](/src/aiogram_webhook/security/checks) for more details.\n\n\n\n\u003e aiogram-webhook — a modular library for professional Telegram bot integration via webhooks with modern Python frameworks.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm-xim%2Faiogram-webhook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fm-xim%2Faiogram-webhook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm-xim%2Faiogram-webhook/lists"}