Integrations

Overview

Bleep delivers violation alerts in real-time via HTTP webhooks or email. When a policy violation is detected, Bleep formats the alert for your chosen platform and delivers it with automatic retry.

Email delivery uses your own SMTP server - one HTML-formatted email per violation, sent instantly to all configured recipients.

How it works

1. A violation is detected by the Bleep proxy
2. The violation is sent to the admin server
3. The admin server dispatches to all enabled webhooks in the background
4. Each webhook receives a platform-formatted payload via HTTP POST (or email via SMTP)
5. Failed deliveries are retried up to 3 times with exponential backoff (1s, 2s, 4s)

Supported platforms

Setup guides

Slack

1. Go to your Slack workspace at api.slack.com/apps
2. Create a new app (or use existing) and enable Incoming Webhooks
3. Click "Add New Webhook to Workspace" and select a channel
4. Copy the webhook URL (starts with https://hooks.slack.com/services/...)
5. In Bleep Dashboard → Integrations, click the Slack tile
6. Paste the URL, set a name and minimum severity, then Save

Microsoft Teams

1. In Teams, navigate to the channel where you want alerts
2. Click the "..." menu → Connectors → Incoming Webhook
3. Name it "Bleep Alerts" and click Create
4. Copy the webhook URL
5. In Bleep Dashboard → Integrations, click the Teams tile
6. Paste the URL, configure severity threshold, then Save

Discord

1. In Discord, go to Channel Settings → Integrations → Webhooks
2. Click "New Webhook" and name it "Bleep Alerts"
3. Copy the webhook URL
4. In Bleep Dashboard → Integrations, click the Discord tile
5. Paste the URL and Save

PagerDuty

1. In PagerDuty, go to Services → your service → Integrations
2. Add a new integration using Events API v2
3. Copy the Integration Key (routing key)
4. In Bleep Dashboard → Integrations, click the PagerDuty tile
5. Set URL to https://events.pagerduty.com/v2/enqueue
6. Paste the Integration Key into the Secret field
7. Set minimum severity (maps to PagerDuty severity: LOW→info, MEDIUM→warning, HIGH→error, CRITICAL→critical)

Custom Webhook

1. Enter any URL that accepts POST requests with JSON body
2. Optionally set a secret sent in the X-Webhook-Secret header
3. Bleep sends a JSON envelope with fields: event, source, timestamp, data

Email (SMTP)

1. In Bleep Dashboard → Integrations, click the Email (SMTP) tile
2. Enter your SMTP host and port (default 587)
3. Enter your SMTP username and password
4. Enable TLS (recommended for secure delivery)
5. Set the From address (e.g. bleep-alerts@yourcompany.com)
6. Add one or more recipient email addresses (comma-separated)
7. Optionally set a display name and minimum severity threshold
8. Click Save, then use Send Test Email to verify delivery

Severity filtering

Each webhook has a minimum severity threshold. Only violations at or above this level are delivered. Levels from lowest to highest:

Testing integrations

After configuring a webhook or email integration, use the Test button to send a sample HIGH-severity violation.

Webhooks

1. Find your webhook in the Active Integrations table
2. Click the play button in the Actions column
3. A success or failure banner will appear

Email (SMTP)

1. Open the Email (SMTP) configuration modal
2. Click Send Test Email
3. A sample violation email is sent to all configured recipients
4. Check your inbox (and spam folder) to confirm delivery

Payload formats

Custom Webhook (JSON Envelope)

{
  "event": "violation",
  "source": "bleep-ai-guard",
  "timestamp": "2025-01-15T14:30:00.000Z",
  "data": {
    "id": 42,
    "severity": "HIGH",
    "pattern_name": "Credit Card Number",
    "action_taken": "BLOCK",
    "destination_host": "api.openai.com",
    "direction": "outbound",
    ...
  }
}

Slack (Block Kit)

{
  "attachments": [{
    "color": "#f97316",
    "blocks": [
      { "type": "header", "text": { ... } },
      { "type": "section", "fields": [
        { "type": "mrkdwn", "text": "*Severity:*\nHIGH" },
        { "type": "mrkdwn", "text": "*Action:*\nBLOCK" },
        ...
      ]},
      { "type": "context", "elements": [...] }
    ]
  }]
}

Discord (Embed)

{
  "embeds": [{
    "title": "Bleep Violation: Credit Card Number",
    "color": 16744256,
    "fields": [
      { "name": "Severity", "value": "HIGH", "inline": true },
      { "name": "Action", "value": "BLOCK", "inline": true },
      { "name": "Destination", "value": "api.openai.com", "inline": true },
      { "name": "Pattern", "value": "Credit Card Number", "inline": true },
      ...
    ],
    "footer": { "text": "Bleep AI Guard" },
    "timestamp": "2025-01-15T14:30:00.000Z"
  }]
}

PagerDuty (Events API v2)

{
  "routing_key": "your-integration-key",
  "event_action": "trigger",
  "payload": {
    "summary": "Bleep Violation: Credit Card Number [HIGH]",
    "severity": "error",
    "source": "bleep-ai-guard",
    "component": "api.openai.com",
    "custom_details": { ... }
  }
}

Email format

Emails are inline-styled HTML for maximum compatibility. Each contains a single violation with a color-coded severity bar.

Subject line

Email body includes

• Color-coded severity bar (blue=LOW, yellow=MEDIUM, orange=HIGH, red=CRITICAL)
• Violation details table: pattern name, severity, action taken, destination, direction
• Timestamp of the violation

Troubleshooting

Email (SMTP) issues