Healthchecks is an open-source monitoring service built with Python and Django that tracks the execution of cron jobs and background tasks by listening for HTTP requests and email messages called "pings" from scheduled checks. When a ping fails to arrive within an expected timeframe, the service automatically sends out alerts to notify users of potential failures. The project is available both as a hosted service at healthchecks.io and as a self-hosted solution with Docker support.
The core functionality revolves around a web-based dashboard that displays the real-time status of all monitored cron jobs and scheduled tasks. Users can configure checks with two key parameters: Period, which defines the expected time between pings, and Grace Time, which specifies how long to wait before triggering alerts when a job runs late. The service also supports defining expected schedules using cron expressions, leveraging the cronsim library for parsing and evaluation. The dashboard provides live-updating event logs for individual checks, allowing users to monitor execution history and identify patterns in job performance.
Healthchecks includes over 25 integrations for delivering notifications across various platforms and services. The platform features a comprehensive REST API for programmatic access, monthly email reports, WebAuthn two-factor authentication support, and team management capabilities including project organization and role-based access control with read-only options. Status badges with public but hard-to-guess URLs enable users to display check status in READMEs, dashboards, and status pages.
The technical foundation uses Python 3.12 or later with Django 6.0, supporting PostgreSQL, MySQL, or MariaDB as database backends. The project is licensed under the BSD 3-clause license. Development setup is documented in the CONTRIBUTING.md file, with instructions for creating a virtual environment, installing dependencies, and running tests. The application reads configuration from environment variables with optional overrides via a local_settings.py file, following Django conventions.
The repository shares contributors with home-assistant/core, immich-app/immich, and gitpod-io/gitpod, suggesting cross-project collaboration within the open-source ecosystem.
The service includes management commands for critical operational tasks such as sending alerts via the sendalerts command, which continuously polls the database for state changes and dispatches notifications. The sendreports command handles monthly reports, weekly reports, and daily or hourly reminders. Automatic database cleanup removes old ping entries, with users able to configure retention limits through the administration panel. Additional maintenance commands handle user account cleanup, rate-limiting record removal, and external object storage pruning. The platform supports external authentication via HTTP headers for integration with existing authentication systems like LDAP or OAuth, and can optionally store large ping bodies in S3-compatible object storage.
