aiogram-webhook 0.0.3

A python library for integrating webhook support with multiple web frameworks in aiogram. Organizes bot operation via webhooks for both single and multi-bot setups.

aiogram-webhook

aiogram-webhook is a 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.

✨ Features

• 🧱 Modular and extensible webhook engine
• 🔀 Flexible routing (static and token-based)
• 🤖 Supports single and multi-bot setups
• ⚡ FastAPI adapters out of the box
• 🔒 Security best practices: secret tokens, IP checks
• 🧩 Easy to extend with custom adapters and routing

🚀 Installation

uv add aiogram-webhook
# or
pip install aiogram-webhook

⚡ Quick Start

Single Bot Example (FastAPI)

import uvicorn
from contextlib import asynccontextmanager
from fastapi import FastAPI
from aiogram import Bot, Dispatcher, Router
from aiogram.filters import CommandStart
from aiogram.types import Message
from aiogram_webhook import SimpleEngine, FastApiWebAdapter
from aiogram_webhook.routing import PathRouting

router = Router()

@router.message(CommandStart())
async def start(message: Message):
    await message.answer("OK")

dispatcher = Dispatcher()
dispatcher.include_router(router)
bot = Bot("BOT_TOKEN_HERE")

engine = SimpleEngine(
    dispatcher,
    bot,
    web_adapter=FastApiWebAdapter(),
    routing=PathRouting(url="/webhook"),
)

@asynccontextmanager
async def lifespan(app: FastAPI):
    engine.register(app)
    await engine.set_webhook(
        drop_pending_updates=True,
        allowed_updates=("message", "callback_query"),
    )
    await engine.on_startup()
    yield
    await engine.on_shutdown()

app = FastAPI(lifespan=lifespan)

if __name__ == "__main__":
    uvicorn.run("main:app", host="0.0.0.0", port=8080)

Multi-Bot Example (FastAPI)

Each bot is configured in Telegram with its own webhook URL: https://example.com/webhook/<BOT_TOKEN>

from aiogram import Dispatcher
from aiogram.client.default import DefaultBotProperties
from aiogram_webhook import TokenEngine, FastApiWebAdapter
from aiogram_webhook.routing import PathRouting

dispatcher = Dispatcher()
engine = TokenEngine(
    dispatcher,
    web_adapter=FastApiWebAdapter(),
    routing=PathRouting(url="/webhook/{bot_token}", param="bot_token"),
    bot_settings={
        "default": DefaultBotProperties(parse_mode="HTML"),
    },
)

Usage is the same:

engine.register(app)
await engine.set_webhook(...)
await engine.on_startup()
await engine.on_shutdown()

🛣️ Routing

PathRouting defines where Telegram sends updates:

• Static path:

  PathRouting(url="/webhook")
  

• Token-based path:

  PathRouting(url="/webhook/{bot_token}", param="bot_token")
  

🛡️ Security

writings...