Integrations

Webhook and Email (SMTP) delivery to Slack, Teams, Discord, PagerDuty, custom endpoints, and email recipients

Overview

Bleep can deliver violation alerts in real-time to your existing notification platforms via HTTP webhooks or email. When a policy violation is detected, Bleep formats the alert for your chosen platform and delivers it via POST request with automatic retry. Bleep also supports email delivery via your own SMTP server — one HTML-formatted email per violation, sent instantly to all configured recipients with the same retry logic.

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

Slack

Rich Block Kit attachments with color-coded severity

Microsoft Teams

MessageCard format with severity theming

Discord

Embeds with inline fields and color sidebar

PagerDuty

Events API v2 triggers with severity mapping

Custom Webhook

Raw JSON envelope to any HTTP endpoint

Email (SMTP)

HTML-formatted violation emails via your SMTP server

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 that will be 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 (e.g. "Bleep Alerts") 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 will be delivered. Severity levels from lowest to highest:

LOW
Informational
MEDIUM
Potential risk
HIGH
Sensitive data
CRITICAL
Immediate action

Testing Integrations

After configuring a webhook or email integration, use the Test button to send a sample violation. The test sends a realistic HIGH-severity violation to verify connectivity. You will see the result immediately in the dashboard.

Webhooks:

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

Email (SMTP):

  1. Open the Email (SMTP) configuration modal
  2. Click Send Test Email
  3. A sample HIGH-severity 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": "plain_text", "text": "Bleep Violation: Credit Card Number" } },
      { "type": "section", "fields": [
        { "type": "mrkdwn", "text": "*Severity:*\nHIGH" },
        { "type": "mrkdwn", "text": "*Action:*\nBLOCK" },
        { "type": "mrkdwn", "text": "*Destination:*\napi.openai.com" },
        { "type": "mrkdwn", "text": "*Direction:*\noutbound" }
      ]},
      { "type": "context", "elements": [{ "type": "mrkdwn", "text": "Bleep AI Guard | 2025-01-15T14:30:00Z" }] }
    ]
  }]
}

PagerDuty (Events API v2)

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

Email Format

Email notifications are sent as inline-styled HTML for maximum compatibility across email clients. Each email contains a single violation with a color-coded severity bar.

Subject line

[Bleep] HIGH Violation: Credit Card Number on api.openai.com

Email body includes

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

Troubleshooting

Test returns "connection refused"

The webhook URL may be unreachable from the admin server. Check firewall rules and ensure the URL is correct. If the admin server is behind a proxy, outbound HTTPS must be allowed.

HTTP 403 or 401 errors

The webhook endpoint requires authentication. For PagerDuty, ensure the Integration Key is set in the Secret field. For custom endpoints, verify any required headers or tokens.

Deliveries show as "Failing"

Bleep retries failed deliveries 3 times with exponential backoff (1s, 2s, 4s). If all attempts fail, the webhook is marked as failing. Check the webhook URL is still valid and the receiving service is online.

No webhooks firing for violations

Verify the webhook is enabled (toggle switch in the Active Integrations table) and the minimum severity threshold is set low enough to match the violations being generated.

Email (SMTP) Issues

SMTP connection timeout

Verify the SMTP host and port are correct. Common ports: 587 (TLS/STARTTLS), 465 (SSL), 25 (unencrypted). Check that firewall rules allow outbound connections on the configured port. Ensure the TLS setting matches your server's requirements.

SMTP authentication failed

Double-check the username and password. Some providers (e.g. Gmail, Microsoft 365) require an app-specific password instead of your regular account password. Check your provider's documentation for SMTP authentication requirements.

No emails arriving

Check your spam/junk folder first. Verify that recipient addresses are correct and the email config is enabled. Ensure the minimum severity threshold is low enough to match the violations being generated. Try the "Send Test Email" button to isolate whether the issue is SMTP connectivity or severity filtering.