Aiogram Webhook

Handles the webhook layer for aiogram bots. Registers the endpoint, calls Telegram setWebhook, verifies incoming requests, and manages engine lifecycle.

Quick start PyPI

What it does

FastAPI & aiohttp

Single-bot & multi-bot

SingleBotEngine for one bot. TokenEngine to route many bots by token in the URL.

Typed Route & Security

Build setWebhook URLs with Route. Verify secret tokens and IP ranges with Security.

aiogram stays the same

Routers, filters, FSM, middleware, handlers — untouched. You only change startup and the HTTP layer.

Install

Requires Python 3.10+, aiogram 3.14+, a bot token from @BotFather, and a public HTTPS URL.

pip

uv add "aiogram-webhook[fastapi]"
uv add "aiogram-webhook[aiohttp]"

pip install "aiogram-webhook[fastapi]"
pip install "aiogram-webhook[aiohttp]"

Omit the extra if you build a custom adapter or use route/security helpers only.

PyPI

Minimal app

Replace BOT_TOKEN, https://example.com, and webhook-secret. base_url must be the HTTPS origin Telegram can reach.

FastAPI

aiohttp

from contextlib import asynccontextmanager

import uvicorn
from aiogram import Bot, Dispatcher, Router
from aiogram.filters import CommandStart
from aiogram.types import Message
from fastapi import FastAPI

from aiogram_webhook import FastAPIAdapter, SingleBotEngine, WebhookConfig
from aiogram_webhook.route import Route
from aiogram_webhook.security import IPCheck, Security, StaticSecretToken

router = Router()


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


dispatcher = Dispatcher()
dispatcher.include_router(router)

bot = Bot("BOT_TOKEN")
engine = SingleBotEngine(
    dispatcher,
    bot,
    web=FastAPIAdapter(),
    route=Route(base_url="https://example.com", path="/telegram/webhook"),
    security=Security(IPCheck(), secret_token=StaticSecretToken("webhook-secret")),
    webhook_config=WebhookConfig(drop_pending_updates=True),
)


@asynccontextmanager
async def lifespan(app: FastAPI):
    await engine.set_webhook()
    yield


app = FastAPI(lifespan=lifespan)
engine.register(app)


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

from aiohttp import web
from aiogram import Bot, Dispatcher, Router
from aiogram.filters import CommandStart
from aiogram.types import Message

from aiogram_webhook import AiohttpAdapter, SingleBotEngine, WebhookConfig
from aiogram_webhook.route import Route
from aiogram_webhook.security import IPCheck, Security, StaticSecretToken

router = Router()


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


dispatcher = Dispatcher()
dispatcher.include_router(router)

bot = Bot("BOT_TOKEN")
engine = SingleBotEngine(
    dispatcher,
    bot,
    web=AiohttpAdapter(),
    route=Route(base_url="https://example.com", path="/telegram/webhook"),
    security=Security(IPCheck(), secret_token=StaticSecretToken("webhook-secret")),
    webhook_config=WebhookConfig(drop_pending_updates=True),
)


async def set_webhook(app: web.Application) -> None:
    await engine.set_webhook()


app = web.Application()
app.on_startup.append(set_webhook)
engine.register(app)


if __name__ == "__main__":
    web.run_app(app, host="0.0.0.0", port=8000)