petersowah/heimdall

Domain monitoring dashboard for Laravel — SSL, uptime, DNS, and WHOIS checks with multi-channel alerts.

dev-main 2026-05-26 14:52 UTC

Requires

• php: ^8.3
• illuminate/contracts: ^11.0|^12.0|^13.0
• illuminate/database: ^11.0|^12.0|^13.0
• illuminate/http: ^11.0|^12.0|^13.0
• illuminate/mail: ^11.0|^12.0|^13.0
• illuminate/queue: ^11.0|^12.0|^13.0
• illuminate/support: ^11.0|^12.0|^13.0

Requires (Dev)

• laravel/pint: ^1.0
• orchestra/testbench: ^9.0|^10.0|^11.0
• pestphp/pest: ^3.0

MIT

• petersowah

• monitoring
• laravel
• heimdall
• petersowah

README

Domain monitoring dashboard for Laravel. Tracks SSL expiry, uptime, DNS changes, and WHOIS data — with alerts via email, Slack, and Telegram.

Requirements

• PHP ^8.3
• Laravel 11, 12, or 13

Installation

composer require petersowah/heimdall

Publish the config:

php artisan vendor:publish --tag=heimdall-config

Run the migrations:

php artisan migrate

Optionally publish frontend assets:

php artisan vendor:publish --tag=heimdall-assets

Configuration

config/heimdall.php:

return [
    'path' => env('HEIMDALL_PATH', 'heimdall'),   // Dashboard URL path
    'middleware' => ['web', 'auth'],               // Applied to all routes
    'domain' => null,                             // Subdomain, if any
    'alert_emails' => env('HEIMDALL_ALERT_EMAILS', ''), // Comma-separated emails
];

Add to .env:

HEIMDALL_PATH=heimdall
HEIMDALL_ALERT_EMAILS=[e-mail],[e-mail]

Authorization

By default, Heimdall is only accessible in the local environment. To control access in production, define an authorization callback — typically in AppServiceProvider::boot():

use PeterSowah\Heimdall\Heimdall;

Heimdall::auth(function ($user) {
    return in_array($user->email, [
        '[e-mail]',
        '[e-mail]',
    ]);
});

The callback receives the authenticated user and should return true or false. The underlying gate is viewHeimdall, so you can also define it directly:

Gate::define('viewHeimdall', function ($user) {
    return $user->hasRole('admin');
});

Dashboard

Visit /heimdall (or your configured path) after installation. The dashboard is protected by the middleware stack defined in config — auth by default — plus the viewHeimdall gate.

What gets monitored

Check	What it does
SSL	Checks certificate validity and days until expiry. Status: ok > 30 days, warning ≤ 30 days, critical ≤ 7 days
Uptime	HTTP reachability check
DNS	Detects changes in DNS records
WHOIS	Tracks domain registration and expiry

Notifications

Supports three alert channels. Configure via the dashboard's notification settings UI or directly via the heimdall_notification_settings table.

• Email — set HEIMDALL_ALERT_EMAILS in .env
• Slack — provide an incoming webhook URL
• Telegram — provide a bot token and chat ID

Per-domain notification toggles: notify_ssl, notify_domain_expiry, notify_uptime, notify_dns.

API Routes

All routes are prefixed with /{path}/api and named under heimdall.api.*.

GET    /heimdall/api/dashboard
GET    /heimdall/api/domains
POST   /heimdall/api/domains
GET    /heimdall/api/domains/{domain}
PUT    /heimdall/api/domains/{domain}
DELETE /heimdall/api/domains/{domain}
POST   /heimdall/api/domains/{domain}/check          # trigger manual check
GET    /heimdall/api/domains/{domain}/checks
GET    /heimdall/api/domains/{domain}/incidents
GET    /heimdall/api/notification-settings
PUT    /heimdall/api/notification-settings
POST   /heimdall/api/notification-settings/test/slack
POST   /heimdall/api/notification-settings/test/telegram

Database Tables

Table	Purpose
heimdall_domains	Tracked domains
heimdall_checks	Check results per domain per type
heimdall_incidents	Incidents opened/closed per domain
heimdall_notification_settings	Per-user notification config
heimdall_alert_logs	History of sent alerts

Testing

composer test

Changelog

See CHANGELOG for recent changes.

Contributing

PRs welcome. Open an issue first for large changes.

Security

Report vulnerabilities via GitHub Security Advisories.

License

MIT — see LICENSE.