Security
Security runs after route matching and before the update reaches aiogram. It is optional in code and important on any public endpoint.
Configure request verification
The engines work without security=..., but the library emits a warning because webhook endpoints are public HTTP routes.
Use a Telegram secret token, an IP check, or both for production deployments.
Built-in pieces
| Component | What it checks | Details |
|---|---|---|
StaticSecretToken |
X-Telegram-Bot-Api-Secret-Token header |
Secret token |
IPCheck |
Client IP (or first X-Forwarded-For hop) |
IP check |
Security |
Secret token first, then custom checks in order | This page |
Custom verification: Custom checks · per-bot secrets: Custom secret token
Wire it once on the engine
from aiogram_webhook.security import IPCheck, Security, StaticSecretToken
security = Security(
IPCheck(),
secret_token=StaticSecretToken("webhook-secret"),
)
engine = SingleBotEngine(dispatcher, bot, web=adapter, route=route, security=security)
Pass security to the engine, not the adapter — verification stays independent of the web framework.
Note
When a secret token is configured, the engine also sends it in setWebhook. Registration and incoming verification stay aligned without extra configuration.
Production hint
Combine StaticSecretToken with IPCheck() behind one Security instance. Tune IPCheck for your reverse proxy — read IP check — Reverse proxies before trusting X-Forwarded-For.