Modern infrastructure management demands real-time visibility, automated configuration, and resilient alerting mechanisms. The convergence of configuration management tools like Ansible with instant messaging platforms like Telegram has created a highly efficient paradigm for monitoring, security auditing, and operational oversight. This integration allows administrators to receive immediate notifications for critical events, ranging from SSH login attempts to orchestration task completions. By leveraging automated roles, callback plugins, reverse proxy architectures, and enterprise UI frameworks, organizations can construct a robust notification ecosystem that scales from individual pet projects to complex distributed environments. The following analysis details the technical architecture, implementation workflows, security hardening protocols, and troubleshooting methodologies required to deploy and maintain this infrastructure at an expert level.

Architectural Foundations: Real-Time Monitoring via SSH and Ansible

Monitoring SSH logins represents a fundamental security measure for any networked environment. Tracking authentication events enables administrators to detect unauthorized access attempts, maintain precise audit trails of user activity, and receive real-time alerts that bypass the latency and reliability issues inherent in traditional email notification systems. Telegram serves as an optimal delivery mechanism for these alerts due to its lightweight architecture, rapid message delivery, and straightforward application programming interface that integrates seamlessly with shell scripts and automation frameworks. While enterprise environments may prioritize centralized platforms like Slack, PagerDuty, or Opsgenie for advanced audit logging and access control, Telegram remains the preferred choice for lean deployments and small teams seeking immediate visibility without operational overhead.

To automate the deployment of SSH monitoring across multiple nodes, administrators utilize dedicated Ansible roles that configure systems to dispatch login and logout events directly to a designated Telegram channel. The primary role in this ecosystem is wiseelf.ssh_telegram_notify, which is distributed through the Ansible Galaxy repository. This role is natively optimized for Debian and Ubuntu distributions, though the underlying configuration files and system hooks can be adapted for other Linux families with minimal modification. The implementation follows a structured playbook architecture. A typical deployment initiates with a playbook file named playbook-ssh-telegram.yml that targets a group of hosts, enables privilege escalation, and collects system facts before applying the role.

Inventory management requires defining a inventory/hosts file containing the target IP addresses. Rather than embedding sensitive credentials directly into plaintext configuration files, the architecture mandates the use of ansible-vault to encrypt the bot token and chat identifier. This cryptographic layer ensures that secrets remain protected during repository storage and network transmission. The group variables file group_vars/all acts as the secure bridge between the encrypted vault and the automation engine. Once the playbook executes against the inventory, the role modifies system authentication hooks to trigger the notification service upon every successful or failed SSH session establishment. This creates a continuous audit trail that logs user identity, timestamp, and connection metadata directly to the administrator's messaging client.

Automating Notification Delivery with Ansible Callbacks

Beyond host-level monitoring, the Ansible control node itself can be configured to push operational updates directly to Telegram. This is achieved through a custom callback plugin architecture that intercepts execution results and formats them for instant messaging delivery. The plugin requires specific Python libraries to function correctly: pyTelegramBotApi for Telegram API communication, prettytable for formatting structured output, and an upgraded version of the requests library to handle HTTP interactions reliably. Installation is performed through standard package management commands.

$ pip install pyTelegramBotApi
$ pip install prettytable
$ pip install requests --upgrade

The callback mechanism is deployed by downloading the telegram.py script and placing it within the Ansible plugins directory structure. Configuration is handled through the ansible.cfg file, where administrators define the callback whitelist and specify the Telegram bot credentials. The configuration block explicitly declares callback_whitelist = telegram, followed by a [callback_telegram] section containing the bot token, chat identifier, and an optional socket proxy endpoint.

callbackwhitelist = telegram
[callbacktelegram]
tgtoken = ENTERTOKEN
tgchatid = ENTERCHATID
socks5_uri = socks5://localhost:9050

Network restrictions in certain geopolitical regions can block direct connections to Telegram's infrastructure. To circumvent these barriers, the architecture strongly recommends routing callback traffic through a SOCKS5 proxy. The Tor network, configured with a local SOCKS5 listener on port 9050, provides the necessary anonymization and routing capability. This proxy layer ensures uninterrupted alert delivery regardless of regional internet filtering policies. When a playbook executes, the callback plugin captures the execution state and transmits a formatted message to the designated chat, providing immediate feedback on automation success or failure.

Scaling Bot Infrastructure: NGINX Reverse Proxy and Webhook Management

Telegram bots can communicate with the platform through two primary methods: long-polling via getUpdates or webhook registration. Polling introduces unnecessary server load and latency, making webhook registration the industry standard for high-performance deployments. Webhooks require the bot process to listen on specific network ports and respond to HTTPS POST requests from Telegram's servers. The platform strictly limits supported webhook ports to 443, 80, 88, and 8443. Any other port assignments will be rejected by the Telegram API. Furthermore, webhooks mandate Transport Layer Security encryption; unencrypted HTTP connections are explicitly prohibited to protect user data and maintain platform integrity.

A significant architectural constraint emerges when hosting multiple bots on a single physical server. Because Telegram only accepts four specific port values, a standard configuration limits an administrator to running a maximum of four bots per machine. To overcome this limitation and host a dozen or more independent bots, a reverse proxy architecture becomes essential. NGINX serves as the central routing layer, consolidating all incoming webhook traffic through a single listening port, typically 443, while distributing requests to the correct bot process based on URL path segmentation.

The NGINX configuration utilizes an include directive to dynamically load location blocks from a dedicated directory. This modular approach allows administrators to deploy new bots independently without modifying the primary server block. Each bot receives its own .locations file containing a path that incorporates the bot's unique token as the routing identifier.

{{ ansible_managed }}

location /{{ bot.telegram.token }} {
proxysetheader Host $httphost;
proxyredirect off;
proxysetheader X-Forwarded-For $proxyaddxforwardedfor;
proxysetheader X-Real-IP $remoteaddr;
proxysetheader X-Scheme $scheme;
proxypass http://0.0.0.0:{{ bot.port }}/{{ bot.telegram.token }};
}

Security requirements for webhooks necessitate valid SSL/TLS certificates. Rather than manually generating certificates for each bot, administrators can leverage Ansible's cryptographic modules to automate self-signed certificate generation. The community.crypto.openssl_privatekey module creates a 4096-bit RSA private key. The community.crypto.openssl_csr module generates a certificate signing request tied to the public IP address. Finally, community.crypto.x509_certificate produces the self-signed certificate. This automated workflow is functionally equivalent to executing the standard OpenSSL command line utility, but provides idempotent, version-controlled infrastructure management.

Enterprise Orchestration: Ansible Semaphore and Troubleshooting Alert Failures

For teams managing complex automation workflows, Ansible Semaphore provides a web-based interface that simplifies playbook execution, scheduling, and team collaboration. Deploying Semaphore typically involves running the official Docker image semaphoreui/semaphore:latest. The platform includes built-in notification capabilities designed to alert administrators when automated tasks complete successfully or encounter failures. However, integrating Telegram alerts within the Semaphore environment frequently presents configuration challenges.

Administrators attempting to configure Telegram notifications within Semaphore often encounter a scenario where no messages are delivered despite task completion or failure. Diagnostic investigation reveals that the platform attempts to transmit alerts, but the request fails with an HTTP 403 Forbidden error code. This error typically indicates an authentication mismatch, an invalid webhook endpoint, or a rejection by the Telegram API due to malformed request parameters. Resolving this requires verifying the webhook URL structure, ensuring the bot token matches the registered application, and confirming that the network path is not blocked by intermediate firewalls or proxy restrictions. When properly configured, Semaphore's notification engine bridges the gap between orchestration results and real-time messaging, providing operational transparency across distributed automation pipelines.

Implementation Roadmap and Security Hardening

Deploying this integrated infrastructure requires a methodical approach that prioritizes security, scalability, and maintainability. The initial phase involves establishing the Telegram bot credentials and verifying API accessibility through the designated endpoint. The secondary phase focuses on Ansible role distribution, ensuring that system hooks are correctly installed and encrypted secrets are properly vaulted. The third phase addresses network architecture, configuring the reverse proxy to route webhook traffic efficiently while maintaining TLS encryption standards. The final phase involves integrating orchestration platforms like Semaphore, troubleshooting API rejections, and validating end-to-end alert delivery.

Security hardening extends beyond basic credential encryption. Administrators must implement strict access controls on the SSH monitoring hooks, ensuring that only authorized users can modify the notification configuration. The reverse proxy layer should enforce rate limiting to prevent abuse, and the callback plugin should validate request signatures before transmission. By adhering to these protocols, organizations establish a resilient alerting infrastructure that scales gracefully while maintaining zero-trust security principles.

Conclusion

The integration of Ansible automation with Telegram messaging represents a paradigm shift in infrastructure monitoring and operational alerting. By leveraging modular Ansible roles, custom callback plugins, and NGINX reverse proxy architectures, administrators can construct a highly responsive notification system that delivers real-time visibility into SSH authentication events, playbook execution states, and distributed bot deployments. The technical complexity of managing webhook endpoints, certificate generation, and proxy routing is entirely manageable through declarative automation, eliminating manual configuration errors and ensuring consistent deployment across heterogeneous environments. As infrastructure grows in scale and complexity, this architectural pattern provides a robust foundation for security auditing, incident response, and continuous operational oversight, transforming isolated automation tasks into a cohesive, enterprise-grade alerting ecosystem.

Sources

1. Kaidalov Blog (https://kaidalov.com/posts/2025/10/ssh-telegram-notify/)
2. GitHub Repository (https://github.com/dfwmlb/ansible-callback-telegram)
3. Madhead Blog (https://madhead.me/posts/nginx-tg-bots/)
4. GitHub Discussions (https://github.com/semaphoreui/semaphore/discussions/2135)