Notifications

DomainMate supports multiple notification channels to alert you about domain and security issues.

Overview

DomainMate can send notifications to:

GitHub Issues - Create issues automatically
GitLab Issues - Create issues in GitLab
Telegram - Send messages to Telegram chats
Microsoft Teams - Post to Teams channels
Email - Send SMTP emails
Generic Webhooks - POST JSON to any endpoint

Enabling Notifications

Add the --notify flag when running DomainMate:

bash

python src/cli.py --config config.yaml --notify

Without this flag, DomainMate only generates reports without sending alerts.

Configuration Methods

Method 1: Configuration File

yaml

notifications:
  github:
    token: "ghp_xxxxxxxxxxxxxxxxxxxx"
    repo: "user/repo"
  
  telegram:
    bot_token: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
    chat_id: "-1001234567890"
  
  teams:
    webhook_url: "https://outlook.office.com/webhook/..."
  
  email:
    smtp_server: "smtp.gmail.com"
    smtp_port: 587
    user: "your-email@gmail.com"
    password: "your-app-password"
    to: "alerts@example.com"

Security Warning

Do not commit secrets to your repository! Use environment variables instead.

Method 2: Environment Variables (Recommended)

bash

# GitHub
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"
export GITHUB_REPO="user/repo"

# GitLab
export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"
export GITLAB_PROJECT_ID="12345"

# Telegram
export TELEGRAM_BOT_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
export TELEGRAM_CHAT_ID="-1001234567890"

# Microsoft Teams
export TEAMS_WEBHOOK_URL="https://outlook.office.com/webhook/..."

# Email
export EMAIL_SMTP_SERVER="smtp.gmail.com"
export EMAIL_SMTP_PORT="587"
export EMAIL_USER="your-email@gmail.com"
export EMAIL_PASSWORD="your-app-password"
export EMAIL_TO="alerts@example.com"

# Generic Webhook
export GENERIC_WEBHOOK_URL="https://your-api.com/webhook"

# Run with notifications
python src/cli.py --notify

GitHub Issues

Setup

Create a Personal Access Token:
- Go to GitHub Settings → Developer settings → Personal access tokens
- Generate new token (classic)
- Select scopes: repo (full control of private repositories)
- Copy the token

Configure:

bash

export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"
export GITHUB_REPO="username/repository"

Features

Creates issues for critical problems (status = "critical" only)
Attempts to apply a label matching the severity level (label must already exist in the repository)

Example Issue

Title: [DomainMate] Critical: SSL Certificate Expiring Soon - example.com

Body:

⚠️ SSL certificate for example.com expires in 5 days!

Expiration Date: 2025-01-08
Certificate Issuer: Let's Encrypt

Action Required:
- Renew certificate immediately
- Update DNS records if necessary
- Verify auto-renewal is working

Generated by DomainMate
Report: https://your-site.github.io/domainmate/

GitLab Issues

Setup

Create a Personal Access Token:
- Go to GitLab Settings → Access Tokens
- Create new token
- Select scopes: api (full API access)
- Copy the token
Find Project ID:
- Go to your project
- Settings → General
- Project ID is shown at the top

Configure:

bash

export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"
export GITLAB_PROJECT_ID="12345"

Features

Similar to GitHub:

Creates issues for critical events only
Uses labels for categorization (label must exist in the project)

Setup

Create a Bot:
- Message @BotFather on Telegram
- Send /newbot
- Follow instructions to create bot
- Copy the bot token
Get Chat ID:
For personal chat:
- Message your bot
- Visit: https://api.telegram.org/bot<YourBOTToken>/getUpdates
- Find "chat":{"id":123456789}
For group chat:
- Add bot to group
- Visit same URL
- Group chat IDs are negative: -1001234567890

Configure:

bash

export TELEGRAM_BOT_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
export TELEGRAM_CHAT_ID="-1001234567890"

Message Format

🚨 DomainMate Alert - Critical

example.com - SSL Certificate
⏰ Expires in 5 days (2025-01-08)
Issuer: Let's Encrypt

Action required immediately!

Report: https://your-site.github.io/domainmate/

Features

Markdown formatting
Group and private chat support

Microsoft Teams

Setup

Create Incoming Webhook:
- Open Microsoft Teams
- Go to target channel
- Click ⋯ → Connectors → Incoming Webhook
- Name: "DomainMate Alerts"
- Copy the webhook URL

Configure:

bash

export TEAMS_WEBHOOK_URL="https://outlook.office.com/webhook/..."

Message Format

Teams receives a MessageCard payload with color-coded severity and a text section.

Features

Color coding by severity (red for critical, green otherwise)
Simple text format via MessageCard

Email

Setup

Gmail

Enable 2-Factor Authentication
Create App Password:
- Google Account → Security → 2-Step Verification → App passwords
- Generate password for "Mail"
- Copy the 16-character password

Configure:

bash

export EMAIL_SMTP_SERVER="smtp.gmail.com"
export EMAIL_SMTP_PORT="587"
export EMAIL_USER="your-email@gmail.com"
export EMAIL_PASSWORD="xxxx xxxx xxxx xxxx"
export EMAIL_TO="alerts@example.com"

Other Providers

Outlook/Office 365:

bash

export EMAIL_SMTP_SERVER="smtp.office365.com"
export EMAIL_SMTP_PORT="587"

Custom SMTP:

bash

export EMAIL_SMTP_SERVER="mail.yourdomain.com"
export EMAIL_SMTP_PORT="587"
export EMAIL_USER="domainmate@yourdomain.com"
export EMAIL_PASSWORD="your-password"

Email Format

Subject: [DomainMate] Critical Issues Detected

Body:

DomainMate Security Report

Critical Issues: 2
Warnings: 5

Details:

1. example.com - SSL Certificate
   Status: Critical
   Expires in 5 days (2025-01-08)
   
2. mysite.io - Domain Registration
   Status: Warning
   Expires in 25 days (2025-01-28)

Full Report:
https://your-site.github.io/domainmate/

--
Generated by DomainMate

Features

Plain text email body
TLS/STARTTLS supported
Single recipient (EMAIL_TO)

Generic Webhooks

Setup

For custom integrations with Slack, Discord, Zapier, n8n, or custom APIs:

bash

export GENERIC_WEBHOOK_URL="https://your-api.com/webhook"

Payload Format

DomainMate POSTs JSON:

json

{
  "title": "DomainMate Alert",
  "message": "Critical issues detected for example.com",
  "level": "critical",
  "timestamp": "2025-01-03T12:00:00Z",
  "details": {
    "domain": "example.com",
    "monitor": "ssl",
    "status": "critical",
    "message": "Certificate expires in 5 days",
    "expiration_date": "2025-01-08",
    "days_until_expiry": 5
  },
  "report_url": "https://your-site.github.io/domainmate/"
}

Integration Examples

Slack

Use Slack Incoming Webhooks:

bash

export GENERIC_WEBHOOK_URL="https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX"

Format payload for Slack in your webhook handler.

Discord

Use Discord Webhooks:

bash

export GENERIC_WEBHOOK_URL="https://discord.com/api/webhooks/123456789/xxxxxxxxxxxx"

Custom API

Process the JSON payload however you need:

python

@app.post("/webhook")
async def domainmate_webhook(data: dict):
    # Process notification
    # Store in database
    # Trigger alerting
    # Update dashboard
    return {"status": "received"}

Notification Strategy

How the `--notify` Flag Works

When --notify is passed to the CLI, a single aggregated notification is sent to all configured channels listing the total number of issues found.

bash

# Only generates report (no notifications)
python src/cli.py

# Generates report + sends aggregated notification
python src/cli.py --notify

NotificationManager (Advanced)

src/notifications/manager.py provides a NotificationManager class with per-issue deduplication and a 24-hour cooldown. It is not used by the CLI directly but can be integrated into custom workflows.

Alert Levels

GitHub and GitLab issues are only created when the level is "critical". Telegram, Teams, Email, and Webhooks are sent for any level.

Multi-Channel Setup

Enable multiple channels simultaneously:

bash

# All notification channels
export GITHUB_TOKEN="..."
export GITHUB_REPO="user/repo"
export TELEGRAM_BOT_TOKEN="..."
export TELEGRAM_CHAT_ID="..."
export TEAMS_WEBHOOK_URL="..."
export EMAIL_SMTP_SERVER="smtp.gmail.com"
export EMAIL_SMTP_PORT="587"
export EMAIL_USER="..."
export EMAIL_PASSWORD="..."
export EMAIL_TO="..."

python src/cli.py --notify

DomainMate sends to all configured channels.

Testing Notifications

Test your notification setup without waiting for real issues:

bash

# Run in demo mode with notifications
python src/cli.py --demo --notify

This generates mock data with various issues to test all notification channels.

CI/CD Integration

GitHub Actions

yaml

- name: Run DomainMate with Notifications
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    TELEGRAM_BOT_TOKEN: ${{ secrets.TELEGRAM_BOT_TOKEN }}
    TELEGRAM_CHAT_ID: ${{ secrets.TELEGRAM_CHAT_ID }}
  run: |
    python src/cli.py --notify

GitLab CI

yaml

domainmate:
  script:
    - python src/cli.py --notify
  variables:
    GITLAB_TOKEN: $GITLAB_TOKEN
    TELEGRAM_BOT_TOKEN: $TELEGRAM_BOT_TOKEN
    TELEGRAM_CHAT_ID: $TELEGRAM_CHAT_ID

Troubleshooting

GitHub Issues Not Created

Verify token has repo scope
Check repository name format: user/repo
Ensure token hasn't expired
Check repository is accessible

Telegram Not Receiving

Verify bot token is correct
Ensure bot wasn't blocked
Check chat ID (negative for groups)
Confirm bot is member of group

Teams Not Working

Verify webhook URL is complete
Check connector is still configured
Ensure Teams allows webhooks

Test with simple curl:

bash

curl -H "Content-Type: application/json" \
     -d '{"text":"Test"}' \
     $TEAMS_WEBHOOK_URL

Email Not Sending

Verify SMTP server and port
Check username and password
Enable "less secure apps" or use app password
Test with telnet:
bash
```
telnet smtp.gmail.com 587
```

Webhooks Failing

Check endpoint is accessible
Verify accepts JSON POST
Check for authentication requirements

Test with curl:

bash

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"test":"data"}' \
     $GENERIC_WEBHOOK_URL

Best Practices

Security

Never commit secrets - Use environment variables
Use app passwords - Not your main account password
Restrict token scopes - Minimum required permissions
Rotate tokens regularly - Update every 90 days
Use CI/CD secrets - GitHub/GitLab secret management

Reliability

Configure multiple channels - Redundancy in case one fails
Test regularly - Use demo mode to verify
Monitor delivery - Check logs for failures
Set up fallbacks - Email as backup to other channels

Organization

Dedicated channels - Separate Teams/Slack channels for DomainMate
Clear naming - "DomainMate Alerts" in all platforms
Document setup - Keep token/webhook info in password manager
Team access - Share notification channels with team

Next Steps

Configure CLI options in the CLI Usage Guide
Set up automation in the CI/CD Guide
Learn about the API in the API Guide

Notifications ​

Overview ​

Enabling Notifications ​

Configuration Methods ​

Method 1: Configuration File ​

Method 2: Environment Variables (Recommended) ​

GitHub Issues ​

Setup ​

Features ​

Example Issue ​

GitLab Issues ​

Setup ​

Features ​

Telegram ​

Setup ​

Message Format ​

Features ​

Microsoft Teams ​

Setup ​

Message Format ​

Features ​

Email ​

Setup ​

Gmail ​

Other Providers ​

Email Format ​

Features ​

Generic Webhooks ​

Setup ​

Payload Format ​

Integration Examples ​

Slack ​

Discord ​

Custom API ​

Notification Strategy ​

How the --notify Flag Works ​

NotificationManager (Advanced) ​

Alert Levels ​

Multi-Channel Setup ​

Testing Notifications ​

CI/CD Integration ​

GitHub Actions ​

GitLab CI ​

Troubleshooting ​

GitHub Issues Not Created ​

Telegram Not Receiving ​

Teams Not Working ​

Email Not Sending ​

Webhooks Failing ​

Best Practices ​

Security ​

Reliability ​

Organization ​

Next Steps ​

Notifications

Overview

Enabling Notifications

Configuration Methods

Method 1: Configuration File

Method 2: Environment Variables (Recommended)

GitHub Issues

Setup

Features

Example Issue

GitLab Issues

Setup

Features

Telegram

Setup

Message Format

Features

Microsoft Teams

Setup

Message Format

Features

Email

Setup

Gmail

Other Providers

Email Format

Features

Generic Webhooks

Setup

Payload Format

Integration Examples

Slack

Discord

Custom API

Notification Strategy

How the `--notify` Flag Works

NotificationManager (Advanced)

Alert Levels

Multi-Channel Setup

Testing Notifications

CI/CD Integration

GitHub Actions

GitLab CI

Troubleshooting

GitHub Issues Not Created

Telegram Not Receiving

Teams Not Working

Email Not Sending

Webhooks Failing

Best Practices

Security

Reliability

Organization

Next Steps