NotiLens — Real-time Alerts

NotiLens delivers real-time push notifications to your phone or team when tasks start, make progress, hit errors, or finish. No polling — instant alerts.

Get your NOTILENS_TOKEN and NOTILENS_SECRET from your topic settings at https://www.notilens.com.

Sending a Notification

All notifications are sent as a POST to the NotiLens webhook:

POST https://hook.notilens.com/webhook/$NOTILENS_TOKEN/send
X-NOTILENS-KEY: $NOTILENS_SECRET
Content-Type: application/json

Payload Fields

Standard Events and When to Fire Them

Use these canonical event names for consistency across sources:

You may also use any custom event name appropriate to your workflow (e.g. order.placed, deploy.started, pipeline.complete).

Metric Tracking

Attach numeric or string metrics to any event's meta object. NotiLens surfaces these in the dashboard for filtering and analytics.

Recommended meta Fields

Timing (milliseconds):

Counters:

Custom metrics — include any domain-specific values:

"meta": {
  "rows_processed": 4218,
  "rows_failed": 3,
  "tokens_used": 18400,
  "model": "claude-opus-4-6",
  "env": "production",
  "region": "us-east-1"
}

Numeric metrics accumulate meaningfully when charted over time. Include them on task.completed and task.failed events at minimum.

run_id — Unique Run Identification

Generate a run_id at the start of each task run and include it on every event for that run. This allows NotiLens to correlate all events from the same execution even if task_id is reused across runs.

run_id format: run_{unix_ms}_{random_hex4}
example:       run_1714000000000_a3f2

Loop Detection

Fire task.loop when the same step is repeating. Include the loop count in meta.

curl -s -X POST "https://hook.notilens.com/webhook/$NOTILENS_TOKEN/send" \
  -H "Content-Type: application/json" \
  -H "X-NOTILENS-KEY: $NOTILENS_SECRET" \
  -d '{
    "event": "task.loop",
    "title": "my-app | scraper | task.loop",
    "message": "Same page returned 5 times — possible infinite loop.",
    "type": "warning",
    "agent": "my-app",
    "task_id": "scraper",
    "run_id": "run_1714000000000_a3f2",
    "is_actionable": true,
    "meta": {
      "loop_count": 5
    }
  }'

Examples

Full task lifecycle (queue → start → complete with metrics)

# 1. Queued
curl -s -X POST "https://hook.notilens.com/webhook/$NOTILENS_TOKEN/send" \
  -H "Content-Type: application/json" \
  -H "X-NOTILENS-KEY: $NOTILENS_SECRET" \
  -d '{
    "event": "task.queued",
    "title": "my-app | data-pipeline | task.queued",
    "message": "Data pipeline job queued.",
    "type": "info",
    "agent": "my-app",
    "task_id": "data-pipeline",
    "run_id": "run_1714000000000_a3f2"
  }'

# 2. Started
curl -s -X POST "https://hook.notilens.com/webhook/$NOTILENS_TOKEN/send" \
  -H "Content-Type: application/json" \
  -H "X-NOTILENS-KEY: $NOTILENS_SECRET" \
  -d '{
    "event": "task.started",
    "title": "my-app | data-pipeline | task.started",
    "message": "Starting nightly data pipeline run.",
    "type": "info",
    "agent": "my-app",
    "task_id": "data-pipeline",
    "run_id": "run_1714000000000_a3f2",
    "meta": { "queue_ms": 1240 }
  }'

# 3. Completed with metrics
curl -s -X POST "https://hook.notilens.com/webhook/$NOTILENS_TOKEN/send" \
  -H "Content-Type: application/json" \
  -H "X-NOTILENS-KEY: $NOTILENS_SECRET" \
  -d '{
    "event": "task.completed",
    "title": "my-app | data-pipeline | task.completed",
    "message": "Pipeline finished. Processed 4,218 records in 47s.",
    "type": "success",
    "agent": "my-app",
    "task_id": "data-pipeline",
    "run_id": "run_1714000000000_a3f2",
    "meta": {
      "total_duration_ms": 47200,
      "active_ms": 45800,
      "rows_processed": 4218,
      "rows_failed": 0,
      "env": "production"
    }
  }'

Task failed with counters

curl -s -X POST "https://hook.notilens.com/webhook/$NOTILENS_TOKEN/send" \
  -H "Content-Type: application/json" \
  -H "X-NOTILENS-KEY: $NOTILENS_SECRET" \
  -d '{
    "event": "task.failed",
    "title": "my-app | data-pipeline | task.failed",
    "message": "Database connection timed out after 3 retries.",
    "type": "urgent",
    "agent": "my-app",
    "task_id": "data-pipeline",
    "run_id": "run_1714000000000_a3f2",
    "is_actionable": true,
    "meta": {
      "total_duration_ms": 92000,
      "active_ms": 88000,
      "retry_count": 3,
      "error_count": 3,
      "last_error": "connect ETIMEDOUT 10.0.0.5:5432"
    }
  }'

Pause and resume with timing

# Pausing (e.g. hit rate limit)
curl -s -X POST "https://hook.notilens.com/webhook/$NOTILENS_TOKEN/send" \
  -H "Content-Type: application/json" \
  -H "X-NOTILENS-KEY: $NOTILENS_SECRET" \
  -d '{
    "event": "task.paused",
    "title": "my-app | api-sync | task.paused",
    "message": "Rate limit hit — waiting 30s before resuming.",
    "type": "warning",
    "agent": "my-app",
    "task_id": "api-sync",
    "run_id": "run_1714000000000_b7c1",
    "meta": { "pause_count": 1, "wait_reason": "rate_limit" }
  }'

# Resuming
curl -s -X POST "https://hook.notilens.com/webhook/$NOTILENS_TOKEN/send" \
  -H "Content-Type: application/json" \
  -H "X-NOTILENS-KEY: $NOTILENS_SECRET" \
  -d '{
    "event": "task.resumed",
    "title": "my-app | api-sync | task.resumed",
    "message": "Resuming after rate limit window.",
    "type": "info",
    "agent": "my-app",
    "task_id": "api-sync",
    "run_id": "run_1714000000000_b7c1",
    "meta": { "pause_ms": 31200, "pause_count": 1 }
  }'

Human input required

curl -s -X POST "https://hook.notilens.com/webhook/$NOTILENS_TOKEN/send" \
  -H "Content-Type: application/json" \
  -H "X-NOTILENS-KEY: $NOTILENS_SECRET" \
  -d '{
    "event": "input.required",
    "title": "my-app | approval needed",
    "message": "About to delete 83 records. Please confirm.",
    "type": "warning",
    "agent": "my-app",
    "is_actionable": true,
    "open_url": "https://dashboard.example.com/approve/123"
  }'

Output generated (with download link)

curl -s -X POST "https://hook.notilens.com/webhook/$NOTILENS_TOKEN/send" \
  -H "Content-Type: application/json" \
  -H "X-NOTILENS-KEY: $NOTILENS_SECRET" \
  -d '{
    "event": "output.generated",
    "title": "my-app | report-gen | output.generated",
    "message": "Monthly report ready. 24 pages, 3 charts.",
    "type": "success",
    "agent": "my-app",
    "task_id": "report-gen",
    "download_url": "https://storage.example.com/reports/2026-04.pdf",
    "meta": {
      "pages": 24,
      "charts": 3,
      "total_duration_ms": 18400
    }
  }'

Usage Guidance

• Always fire task.started when beginning a significant task so the user knows work has begun.
• Fire task.completed or task.failed at every terminal state — never leave a started task without a closing event.
• Generate a run_id at task start (run_{unix_ms}_{random_hex4}) and include it on every event for that run.
• Include timing in meta on terminal events (task.completed, task.failed, task.timeout) — total_duration_ms and active_ms at minimum.
• Include counters in meta whenever they are non-zero: retry_count, error_count, loop_count, pause_count, wait_count.
• Use input.required with is_actionable: true whenever a human decision is needed before continuing.
• Fire task.loop when the same logical step is repeating. Include loop_count in meta.
• Keep message concise and informative — include counts, durations, or key values (e.g. "Processed 1,240 rows in 3.2s — 2 errors").
• Use task_id consistently across all events for the same logical task so NotiLens can group them.
• Do not spam — avoid sending task.progress more than once every few seconds for fast-running tasks.

Configuration

Set these environment variables before running:

export NOTILENS_TOKEN=your_topic_token
export NOTILENS_SECRET=your_topic_secret

Both are found in your topic settings at https://www.notilens.com.