Skip to main content

102. Webhook Architecture for Bots

Status: Accepted Date: 2025-07-06

Context​

There are two ways for a Telegram bot to receive updates (new messages, button clicks, etc.) from the Telegram API:

  1. Long Polling: The bot server makes a long-lived HTTP request to Telegram's servers, which holds the connection open until a new update is available. This is simple and works anywhere, even on a local developer machine without a public IP address.
  2. Webhooks: We provide Telegram with a public HTTPS URL. Whenever there is a new update for our bot, Telegram's servers will make a POST request to our URL with the update payload.

For a production environment, long polling is inefficient. It requires a constantly open connection and introduces a delay between the update happening and it being received.

Decision​

We will use long polling for local development and webhooks for all production deployments.

  • The kaido-telegram library will be designed to support both methods.
  • For local development (e.g., when NODE_ENV is development), the bot will start in long polling mode by default.
  • For production deployments, our application will expose an HTTP endpoint (e.g., /api/telegram/webhook/<bot_token>). We will register this URL with Telegram. The TelegramBotService will be responsible for setting up a webhook handler that listens for requests on this endpoint and processes the incoming updates.

Consequences​

Positive:

  • Efficiency and Scalability: Webhooks are much more efficient. We don't need to maintain a persistent open connection to Telegram. Our server only uses resources when it is actively receiving an update. This is the recommended and most scalable approach for production bots.
  • Instantaneous Updates: Updates are pushed to our server the instant they happen, resulting in lower latency and a more responsive bot.
  • Best of Both Worlds: This dual approach provides the efficiency of webhooks in production with the simplicity of long polling for local development, where setting up a public HTTPS endpoint would be a hassle.

Negative:

  • Requires a Public URL: Webhooks require our application to be accessible from the public internet via a secure (HTTPS) URL. This requires more complex network configuration (e.g., a reverse proxy, SSL certificates).
  • Security Considerations: Exposing a public endpoint means we must secure it to prevent denial-of-service attacks or spoofed updates.

Mitigation:

  • Standard Production Infrastructure: Our production deployment infrastructure already includes a reverse proxy (like Nginx or Traefik) that handles SSL termination and exposes services to the internet. We are simply adding another endpoint to this existing setup.
  • Webhook Security Best Practices: We will follow Telegram's security best practices. The webhook URL will contain a secret token that is only known to our application and Telegram. The middleware that handles the webhook request will validate this token to ensure the request is legitimate. We can also whitelist Telegram's IP addresses at our firewall as an additional layer of security.