Aiforsite Alerts User Guide

1. Getting Started

Aiforsite Alerts is a multi-channel alerting platform that helps you monitor your services and get notified when things go wrong.

Key Features

• Alert Ingestion - Receive alerts via webhook from any system
• Health Monitors - HTTP endpoint and script-based health checks
• Heartbeat Monitoring - Dead man's switch for cron jobs and backups
• AI Watchers - Monitor web pages for changes with AI analysis
• Status Page - Public status page for your services
• Multi-channel Notifications - Email, SMS, Slack, WhatsApp, Webhooks

2. API Keys

API keys are used to authenticate requests to the Aiforsite Alerts API.

Creating an API Key

1. Go to Admin → API Keys
2. Click "Add API Key"
3. Enter a name and select scope
4. Important: Copy the key immediately - it's only shown once!

Scopes

Using API Keys

# Header authentication (recommended)
curl -H "Authorization: ApiKey al_xxxx_xxxxxx" \
     https://alerts.aiforsite.io/api/v1/...

# Bearer token format also works
curl -H "Authorization: Bearer al_xxxx_xxxxxx" \
     https://alerts.aiforsite.io/api/v1/...

3. Sending Alerts

Send alerts to Aiforsite Alerts from any system using our ingest API.

Basic Alert

curl -X POST https://alerts.aiforsite.io/api/v1/ingest/ \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alerts": [{
      "name": "High CPU Usage",
      "message": "Server CPU is at 95%",
      "level": "warning"
    }]
  }'

Alert Levels

Full Payload Example

{
  "project": {
    "id": "proj-123",
    "name": "Production Server"
  },
  "alerts": [{
    "name": "Database Connection Failed",
    "message": "Cannot connect to PostgreSQL",
    "level": "critical"
  }],
  "device": {
    "name": "web-server-01",
    "serial": "ABC123"
  }
}

4. Health Monitors

Automatically check if your services are healthy.

HTTP Monitors

Check if an HTTP endpoint is responding correctly.

• URL to check
• Expected status code (default: 200)
• Response must contain specific text
• Maximum response time
• Check interval (5 min to 24 hours)

Script Monitors

Run custom Python or Bash scripts to check anything.

#!/bin/bash
# Check disk usage
USAGE=$(df / | tail -1 | awk '{print $5}' | sed 's/%//')
if [ $USAGE -gt 90 ]; then
    echo "Disk usage critical: ${USAGE}%"
    exit 1
fi
echo "Disk OK: ${USAGE}%"
exit 0

Exit code 0 = OK, non-zero = FAIL

Alert Settings

• Alert after N failures - Only alert after consecutive failures (default: 2)
• Recovery alerts - Get notified when service recovers

5. Heartbeat Monitoring

Monitor cron jobs, backups, and scheduled tasks. Alert if they don't run on time.

How It Works

1. Create a heartbeat with expected interval
2. Get unique ping URL
3. Add ping to your script/cron job
4. Get alerted if ping is missing

Example: Backup Script

#!/bin/bash
# backup.sh

# Run backup
pg_dump mydb > backup.sql

# Ping heartbeat on success
curl -s https://alerts.aiforsite.io/api/v1/heartbeat/YOUR_TOKEN/

Crontab Example

# Run backup daily at 2 AM, ping heartbeat on success
0 2 * * * /opt/scripts/backup.sh && curl -s https://alerts.aiforsite.io/api/v1/heartbeat/YOUR_TOKEN/

Settings

• Interval - How often the ping is expected
• Grace period - Extra time before alerting

6. AI Watchers

Monitor web pages and get alerted when specific conditions are met using AI analysis.

Use Cases

• Concert tickets become available
• Product comes back in stock
• Price drops below threshold
• Job posting appears
• News article is published

Creating a Watcher

1. Go to Admin → Watchers
2. Enter the URL to monitor
3. Write a condition in plain language:
   "Alert me when concert tickets become available"
   "Notify me if price drops below 100€"
4. Set check interval
5. Select notification channels

How It Works

1. Aiforsite Alerts fetches the page periodically
2. Compares content with previous version
3. AI analyzes if your condition is met
4. Sends notification if condition is true

Note: Requires OPENAI_API_KEY environment variable.

7. Status Page

Public status page showing the health of your services.

Features

• Real-time status of monitors and heartbeats
• Uptime percentages
• Response time metrics
• Incident history
• Custom branding (logo, colors)
• Auto-refresh every 60 seconds

Setup

1. Go to Admin → Status Pages
2. Create a new status page
3. Choose a URL slug (e.g., status)
4. Select monitors and heartbeats to display
5. Share URL: https://alerts.aiforsite.io/status/your-slug/

JSON API

GET /api/v1/status/your-slug/

{
  "title": "My Company Status",
  "overall_status": "operational",
  "monitors": [
    {"name": "API", "status": "ok"},
    {"name": "Website", "status": "ok"}
  ],
  "heartbeats": [
    {"name": "Daily Backup", "status": "healthy"}
  ]
}

8. Notification Channels

Configure where and how you receive alerts.

Supported Channels

Email Setup (Gmail)

1. Go to Admin → Email Settings
2. Select "Gmail SMTP" provider
3. Enter your Gmail address
4. Create an App Password at Google Account
5. Enter the App Password

Slack Setup

1. Create an Incoming Webhook in Slack
2. Go to Admin → Notification Channels
3. Add new channel, select "Slack"
4. Paste the webhook URL

Need Help?

Contact support or check our GitHub repository for issues and updates.