Notifications¶

Pisama routes detection alerts to Slack, Discord, or email. All channels are configured per-tenant via the preferences API. No environment variables or server restarts required.

Quick setup¶

curl -X PUT https://api.pisama.ai/api/v1/tenants/{id}/preferences/notifications \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "min_severity": "warning",
    "channels": {
      "slack": {
        "enabled": true,
        "webhook_url": "https://hooks.slack.com/services/T.../B.../..."
      }
    }
  }'

Pisama sends a Slack message whenever a detection at or above min_severity fires for an ingested trace. No polling, no dashboards required.

Channels¶

Slack¶

Create an incoming webhook at https://api.slack.com/messaging/webhooks and paste the URL. Messages use Block Kit format with detection type, confidence, trace ID, and a timestamp.

{
  "channels": {
    "slack": {
      "enabled": true,
      "webhook_url": "https://hooks.slack.com/services/..."
    }
  }
}

Discord¶

Same pattern. Create a webhook under Server Settings > Integrations > Webhooks.

{
  "channels": {
    "discord": {
      "enabled": true,
      "webhook_url": "https://discord.com/api/webhooks/..."
    }
  }
}

Email¶

{
  "channels": {
    "email": {
      "enabled": true,
      "addresses": ["oncall@yourcompany.com", "ai-team@yourcompany.com"]
    }
  }
}

Severity levels¶

Start at warning. Drop to info once you have a sense of the noise floor on your traces.

Per-detector severity overrides¶

Raise the bar for noisy detectors or lower it for ones you care about most, without changing the tenant-wide floor:

{
  "min_severity": "warning",
  "per_detector": {
    "hallucination": { "min_severity": "critical" },
    "output_validation": { "min_severity": "info" }
  }
}

Quiet hours¶

Suppress non-critical alerts during off-hours:

{
  "quiet_hours": {
    "enabled": true,
    "start": "22:00",
    "end": "07:00",
    "timezone": "America/Los_Angeles",
    "severity_floor_during": "critical"
  }
}

severity_floor_during: "critical" means only critical-severity detections fire during the quiet window. Warning and below are held until the window ends.

Read current preferences¶

curl https://api.pisama.ai/api/v1/tenants/{id}/preferences/notifications \
  -H "Authorization: Bearer $TOKEN"

Detector threshold tuning¶

Notification volume is controlled by two independent knobs:

1. Notification severity floor (min_severity above) — filters which detections trigger an alert after they are already stored.

2. Detector confidence threshold — controls whether a detection fires at all. Raise this to reduce detection volume at the source.

curl -X PUT https://api.pisama.ai/api/v1/tenants/{id}/settings/detector-overrides \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "output_validation": 0.4,
    "hallucination": 0.75,
    "persona_drift": 0.8
  }'

Values between 0 and 1. Lower value = more detections (higher recall). Higher value = fewer detections (higher precision). Changes take effect immediately on the next ingested trace.

To reset a detector back to the globally calibrated threshold:

DELETE /api/v1/tenants/{id}/settings/detector-overrides/hallucination