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

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

# 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

# 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:

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

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

Step 2: Configure in Purl

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

PURL_ALERT_WEBHOOK_URL=https://your-service.com/webhooks/purl
PURL_ALERT_WEBHOOK_SECRET=your-hmac-secret  # optional

Step 2: Payload Format

Purl sends this JSON payload:

{
  "alert_name": "High Error Rate",
  "triggered_at": "2026-02-18T10:30:00Z",
  "query": "level:error AND source:api",
  "match_count": 47,
  "threshold": 10,
  "window": "5m",
  "sample_logs": [
    {
      "timestamp": "2026-02-18T10:29:55Z",
      "level": "error",
      "message": "Connection timeout to database",
      "source": "api-server"
    }
  ],
  "dashboard_url": "https://your-purl:3000/search?q=level:error"
}

PagerDuty Example

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

Creating Alert Rules

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

1. 1Name: "High Error Rate — API"
2. 2Query: level:error AND source:api-server
3. 3Threshold: More than 10 matches
4. 4Window: In the last 5 minutes
5. 5Channels: Select Telegram, Slack, or Webhook
6. 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