Why Alerting Matters

Logs are only useful if someone reads them. In practice, no one monitors logs 24/7 — that's what alerts are for. A well-configured alerting system catches issues in minutes instead of hours.

Purl supports three alert channels out of the box: Telegram, Slack, and Webhooks. Let's set up all three.

Telegram Alerts

Telegram is the fastest way to get started — no OAuth, no app approval, just a bot token.

Step 1: Create a Telegram Bot

bash # Message @BotFather on Telegram: /newbot # Choose a name: "Purl Alerts" # Choose a username: "purl_alerts_bot" # Copy the bot token: 123456:ABC-DEF... ```

# Message @BotFather on Telegram:
/newbot
# Choose a name: "Purl Alerts"
# Choose a username: "purl_alerts_bot"
# Copy the bot token: 123456:ABC-DEF...

Step 2: Get Your Chat ID

bash # Send any message to your bot, then: curl "https://api.telegram.org/bot<TOKEN>/getUpdates" # Find chat.id in the response ```

# Send any message to your bot, then:
curl "https://api.telegram.org/bot<TOKEN>/getUpdates"
# Find chat.id in the response

Step 3: Configure in Purl

Set environment variables:

bash PURL_TELEGRAM_BOT_TOKEN=123456:ABC-DEF... PURL_TELEGRAM_CHAT_ID=-1001234567890 ```

PURL_TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
PURL_TELEGRAM_CHAT_ID=-1001234567890

Or configure in Settings → Alerts → Telegram in the dashboard.

Slack Alerts

Step 1: Create a Slack Webhook

1Go to api.slack.com/apps → Create New App
2Choose "From scratch", select your workspace
3Go to "Incoming Webhooks" → Activate
4Click "Add New Webhook to Workspace"
5Choose the channel → Copy the webhook URL

Step 2: Configure in Purl

bash PURL_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T.../B.../xxx ```

PURL_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T.../B.../xxx

Slack alerts include rich formatting with log level colors, source info, and a direct link to the matching logs in Purl.

Webhook Alerts (PagerDuty, Discord, Custom)

The webhook channel sends a POST request with a JSON payload to any URL. This enables integration with any service.

Step 1: Configure Webhook URL

bash PURL_ALERT_WEBHOOK_URL=https://your-service.com/webhooks/purl PURL_ALERT_WEBHOOK_TOKEN=your-bearer-token # optional, sent as "Authorization: Bearer <token>" ```

PURL_ALERT_WEBHOOK_URL=https://your-service.com/webhooks/purl
PURL_ALERT_WEBHOOK_TOKEN=your-bearer-token  # optional, sent as "Authorization: Bearer <token>"

Step 2: Payload Format

Purl sends this JSON payload:

json { "event": "purl.alert", "timestamp": 1770287400, "alert": { "title": "High Error Rate", "query": "level:ERROR", "count": 47, "threshold": 10, "window": 5, "severity": "critical", "time": "Wed Feb 18 10:30:00 2026" } } ```

{
  "event": "purl.alert",
  "timestamp": 1770287400,
  "alert": {
    "title": "High Error Rate",
    "query": "level:ERROR",
    "count": 47,
    "threshold": 10,
    "window": 5,
    "severity": "critical",
    "time": "Wed Feb 18 10:30:00 2026"
  }
}

PagerDuty Example

bash PURL_ALERT_WEBHOOK_URL=https://events.pagerduty.com/v2/enqueue ```

PURL_ALERT_WEBHOOK_URL=https://events.pagerduty.com/v2/enqueue

Creating Alert Rules

In the Purl dashboard, go to Settings → Alerts → Create Rule:

1Name: "High Error Rate — API"
2Query: level:error — one filter per rule: level:X, service:X, or free text (substring match on the message)
3Threshold: More than 10 matches
4Window: In the last 5 minutes
5Channels: Select Telegram, Slack, or Webhook
6Cooldown: 15 minutes (prevent alert storms)

Best Practices

Start broad, then narrow: Begin with level:error alerts, then add specific patterns
Use cooldown periods: 15-30 minutes prevents alert fatigue
Alert on anomalies, not absolutes: "10x more errors than usual" > "more than 5 errors"
Route by severity: Telegram for critical, Slack for warnings, Webhook for info
Include context: Purl alerts include sample log entries so you can diagnose without opening the dashboard

Setting Up Log Alerts with Purl: Telegram, Slack, and Webhooks