Healthchecks

Healthchecks is a lightweight, self‑hosted cron job monitoring platform written in Python 3.10+ and built on Django 5.2. It exposes a RESTful API, WebSocket‑based live dashboards, and webhook endpoints that allow developers to integrate job health checks into existing CI/CD pipelines or infrastructure monitoring stacks. The core idea is simple: each scheduled task emits an HTTP request (or email) to a unique “ping” URL; if the ping is not received within a configurable Period plus an optional Grace Time, Healthchecks transitions the check into a Late or Down state and triggers notifications.

• Framework: Django 5.2 with its ORM and authentication system, enabling rapid development of the web UI, API views, and admin interfaces.
• Database: Supports PostgreSQL, MySQL, or MariaDB; the schema is deliberately minimal—tables for Check, Ping, Integration, and audit logs.
• Background Processing: Uses Celery with Redis or RabbitMQ as a broker to handle scheduled jobs, state transitions, and notification dispatch.
• WebSocket Layer: Django Channels powers the live‑updating “My Checks” dashboard, pushing state changes to clients in real time.
• Cron Parsing: Integrates the cronsim library to evaluate cron expressions, allowing checks to be defined via human‑readable schedules instead of fixed periods.

The application follows a micro‑service‑like pattern: the web front‑end, API, and background worker can be deployed in separate containers or on a single host depending on scale.

• Health‑Check API: POST /api/checks/<uuid>/ping/ to record a successful run; GET /api/checks/ returns JSON summaries.
• Webhook & Integration: Built‑in integrations for Slack, Microsoft Teams, PagerDuty, email, and custom webhooks; each integration can be toggled per check.
• Status Badges: Exposes a public URL that returns an SVG badge reflecting the current state; useful for README or internal dashboards.
• Audit & Event Log: Each ping is logged with timestamp, source IP, and optional payload; the event stream can be queried via API or consumed by external log aggregators.
• Security: Supports WebAuthn 2FA, OAuth2 for API access, and per‑user permissions (team, project, read‑only).

All endpoints are documented in the repository’s docs/ folder and auto‑generated OpenAPI specs.

Healthchecks ships with a Dockerfile and pre‑built images (healthchecks/healthchecks on Docker Hub). A single container can run the web server, Celery worker, and Channels layer via a multi‑process supervisor (e.g., supervisord). For production, the typical stack is:

1. PostgreSQL (or MySQL/MariaDB) in a separate container or managed database.
2. Redis for Celery broker and Channels layer.
3. NGINX/Traefik as a reverse proxy with TLS termination.

The application scales horizontally by adding more Celery workers; the Django ORM and Channels layer support multiple replicas behind a load balancer. The lightweight codebase keeps memory usage under 200 MiB per instance, making it suitable for small VMs or Kubernetes deployments.

• Plugin Architecture: Developers can add custom integrations by implementing a simple Integration subclass and registering it in INSTALLED_APPS.
• Webhooks: Any external system can subscribe to check events via the /api/webhooks/ endpoint, receiving JSON payloads on state changes.
• CLI Tools: A management command healthchecks ping can be scripted in cron jobs to send pings programmatically.
• Extensible Auth: Supports LDAP, SAML, or custom authentication backends via Django’s auth system.

The open‑source nature encourages community plugins; the repository already contains dozens of integrations, and contributors can add new ones with minimal boilerplate.

Healthchecks’ documentation is comprehensive: a CONTRIBUTING.md guide, detailed API docs, and a live‑demo instance. The codebase follows PEP8 and uses type hints for static analysis. Unit tests cover 80 %+ of the code, and continuous integration on GitHub ensures every pull request passes linting, tests, and coverage checks. The BSD 3‑clause license allows unrestricted use in commercial or private projects, and the active community on GitHub and Discord provides rapid support for integration questions.

• CI/CD Pipeline Health: Monitor nightly builds, artifact uploads, or database migrations by pinging a check URL after each run.
• Infrastructure Automation: Ensure that backup scripts, log rotation, or security scans execute on schedule.
• Service‑Level Agreements (SLAs): Expose status badges to customers or internal dashboards, automatically notifying ops teams when a job misses its window.
• Legacy System Modernization: Wrap legacy batch jobs with simple HTTP clients (e.g., curl) and gain instant visibility without refactoring the job logic.

• Performance & Flexibility: Lightweight Django app with minimal dependencies, enabling quick