Insights Webhooks

Edison Watch can automatically detect anomalies and security patterns in agent activity and push these insights to external webhook endpoints.

What Are Insights?

Insights are automated security findings generated by Edison Watch's detector plugins:

Detector	Description
Loop Detection	Identifies agents stuck in repetitive patterns
External Write Detection	Flags unusual spikes in external write operations
MCP Dissatisfaction	Detects sessions with high tool call failure rates

Configuration

Insights webhooks are configured via the insights_config.json file in your Edison Watch config directory.

Configuration File Location

The config file is located at:

Linux/macOS: ~/.config/edison-watch/insights_config.json
Windows: %APPDATA%\edison-watch\insights_config.json

Configuration Options

{
  "lookback_hours": 24,
  "detectors": {
    "loop": {
      "enabled": true,
      "window_minutes": 30,
      "min_repeats": 4,
      "max_sessions": 200,
      "max_attempts_per_session": 25
    },
    "external_write": {
      "enabled": true,
      "max_daily_writes": 5,
      "spike_ratio": 2.5
    },
    "mcp_dissatisfaction": {
      "enabled": true,
      "min_calls": 5,
      "failure_ratio": 0.6
    }
  },
  "ranker": {
    "max_results": 3,
    "dedupe_by_actor": true,
    "dedupe_by_detector": false
  },
  "publisher": {
    "enabled": true,
    "dump_path": null,
    "webhook_urls": [
      "https://your-webhook.example.com/insights"
    ]
  }
}

Publisher Settings

Field	Description	Default
enabled	Enable or disable insight publishing	`true`
dump_path	Local file path to write insights (null for default)	`~/.config/edison-watch/insights.log`
webhook_urls	Array of HTTP/HTTPS URLs to send insights to	`[]`

Webhook Payload Format

When insights are detected, they are sent as a POST request to each configured webhook URL:

{
  "source": "edison-watch",
  "event_type": "insights",
  "count": 2,
  "insights": [
    {
      "detector_slug": "loop_detection",
      "title": "Agent stuck in loop",
      "summary": "Agent 'code-assistant' repeated the same action 5 times",
      "severity": "high",
      "score": 0.85,
      "actor": "[email protected]",
      "session_id": "abc-123",
      "created_at": "2026-01-19T10:30:00.000Z",
      "recommended_action": "Review agent configuration and constraints",
      "evidence": {
        "repeated_tool": "filesystem.write_file",
        "repeat_count": 5
      }
    }
  ]
}

Insight Fields

Field	Description
detector_slug	Identifier for the detector that generated the insight
title	Human-readable title for the insight
summary	Detailed description of what was detected
severity	Severity level: `low`, `medium`, `high`, `critical`
score	Confidence score between 0 and 1
actor	User or agent that triggered the insight
session_id	Associated session ID
created_at	ISO 8601 timestamp when the insight was generated
recommended_action	Suggested remediation steps
evidence	Additional context and data specific to the detector

Running the Insight Detector

Insights are generated by running the insight detector:

# Run once with default settings
python -m src.insights.runner
 
# Override lookback window
python -m src.insights.runner --lookback-hours 48
 
# For multi-tenant deployments
python -m src.insights.runner --tenant-id acme-corp

For production deployments, schedule the detector to run periodically (e.g., via cron or a scheduled job).

Integration Examples

Slack Webhook

To send insights to Slack, use a Slack Incoming Webhook URL:

{
  "publisher": {
    "enabled": true,
    "webhook_urls": [
      "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK"
    ]
  }
}

You may need a middleware service to transform the Edison Watch payload into Slack's expected format.

PagerDuty

For PagerDuty integration, use the Events API v2 endpoint:

{
  "publisher": {
    "enabled": true,
    "webhook_urls": [
      "https://events.pagerduty.com/v2/enqueue"
    ]
  }
}

PagerDuty requires specific payload formatting. Consider using a webhook relay service or custom endpoint to transform the payload.

Troubleshooting

Webhooks Not Firing

Check that publisher.enabled is true
Verify webhook URLs are valid HTTP/HTTPS endpoints
Check Edison Watch logs for webhook dispatch errors
Ensure the endpoint is reachable from your Edison Watch server

No Insights Generated

Verify detectors are enabled in the config
Check that there is sufficient session data (lookback window)
Adjust detector thresholds if they're too strict

Need help configuring insights webhooks? Email [email protected].

On this page