Webhooks - Bloom Documentation

Overview

Webhooks allow you to receive real-time HTTP notifications when security events occur. Use them to integrate Bloom with your alerting systems (Slack, PagerDuty, etc.).

Supported Events

Event	Description
`injection_blocked`	Prompt injection attack was detected and blocked
`agent_killed`	An agent was terminated via kill switch
`anomaly_detected`	Unusual agent behavior was detected
`permission_denied`	Agent attempted unauthorized action
`rate_limit_exceeded`	Agent exceeded rate limits
`mcp_tool_blocked`	MCP tool call was blocked by permissions

Creating a Webhook

Dashboard

Go to Activity > Webhooks tab
Click Add Webhook
Configure:
- Name: Descriptive name
- URL: Your HTTPS endpoint
- Secret: Optional HMAC signing secret
- Events: Select which events to receive

API

curl -X POST https://api.bloomtechnologies.app/webhooks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Security Alerts",
    "url": "https://your-server.com/webhook",
    "secret": "your-hmac-secret",
    "events": ["injection_blocked", "agent_killed", "anomaly_detected"]
  }'

Webhook Payload

All webhooks include:

{
  "id": "evt_abc123",
  "event": "injection_blocked",
  "timestamp": "2026-02-01T15:30:00Z",
  "organization_id": "org_xxx",
  "agent_id": "agent_abc123",
  "agent_name": "my-agent",
  "data": {
    // Event-specific data
  }
}

Event-Specific Data

injection_blocked
agent_killed
anomaly_detected
permission_denied

{
  "event": "injection_blocked",
  "data": {
    "pattern_name": "instruction_override",
    "severity": "critical",
    "matched_text": "ignore all previous...",
    "location": "body.messages[0].content",
    "endpoint": "/v1/chat/completions",
    "source_ip": "192.168.1.1"
  }
}

{
  "event": "agent_killed",
  "data": {
    "reason": "Manual kill by admin",
    "triggered_by": "[email protected]",
    "kill_method": "dashboard",
    "requests_terminated": 2,
    "propagation_ms": 47
  }
}

{
  "event": "anomaly_detected",
  "data": {
    "anomaly_score": 0.87,
    "anomaly_types": ["frequency", "new_endpoint"],
    "baseline_deviation": {
      "normal_rpm": 10,
      "current_rpm": 150
    },
    "action_taken": "alert"
  }
}

{
  "event": "permission_denied",
  "data": {
    "attempted_action": "POST /v1/fine-tuning/jobs",
    "service": "openai",
    "reason": "No scope grants access to this endpoint",
    "agent_scopes": ["openai-chat-only"]
  }
}

Signature Verification

If you provide a secret, Bloom signs each webhook with HMAC-SHA256:

X-Bloom-Signature: sha256=abc123...
X-Bloom-Timestamp: 1706803800

Verification Example (Python)

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

# In your webhook handler
@app.post("/webhook")
async def handle_webhook(request: Request):
    payload = await request.body()
    signature = request.headers.get("X-Bloom-Signature")

    if not verify_webhook(payload, signature, WEBHOOK_SECRET):
        raise HTTPException(401, "Invalid signature")

    event = json.loads(payload)
    # Process event...

Verification Example (Node.js)

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(`sha256=${expected}`),
    Buffer.from(signature)
  );
}

Retry Policy

Failed webhook deliveries are retried:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours

After 5 failures, the webhook is marked as failing and you’ll receive an email notification.

Testing Webhooks

From Dashboard

Go to Activity > Webhooks
Find your webhook
Click the Test button (paper plane icon)

This sends a test payload to verify your endpoint is working.

Test Payload

{
  "id": "evt_test_123",
  "event": "test",
  "timestamp": "2026-02-01T15:30:00Z",
  "data": {
    "message": "This is a test webhook from Bloom"
  }
}

Integration Examples

Slack

import requests

@app.post("/webhook")
async def handle_bloom_webhook(request: Request):
    event = await request.json()

    slack_message = {
        "text": f"🚨 Bloom Alert: {event['event']}",
        "blocks": [
            {
                "type": "section",
                "text": {
                    "type": "mrkdwn",
                    "text": f"*Event:* {event['event']}\n*Agent:* {event['agent_name']}\n*Time:* {event['timestamp']}"
                }
            }
        ]
    }

    requests.post(SLACK_WEBHOOK_URL, json=slack_message)

PagerDuty

@app.post("/webhook")
async def handle_bloom_webhook(request: Request):
    event = await request.json()

    if event["event"] in ["agent_killed", "injection_blocked"]:
        requests.post(
            "https://events.pagerduty.com/v2/enqueue",
            json={
                "routing_key": PAGERDUTY_KEY,
                "event_action": "trigger",
                "payload": {
                    "summary": f"Bloom: {event['event']} - {event['agent_name']}",
                    "severity": "critical",
                    "source": "bloom-iam"
                }
            }
        )

Managing Webhooks

List Webhooks

curl https://api.bloomtechnologies.app/webhooks \
  -H "Authorization: Bearer $API_KEY"

Delete Webhook

curl -X DELETE https://api.bloomtechnologies.app/webhooks/{webhook_id} \
  -H "Authorization: Bearer $API_KEY"

View Webhook Stats

In the dashboard, each webhook shows:

Success/failure counts
Last triggered time
Recent delivery attempts

​Overview

​Supported Events

​Creating a Webhook

​Dashboard

​API

​Webhook Payload

​Event-Specific Data

​Signature Verification

​Verification Example (Python)

​Verification Example (Node.js)

​Retry Policy

​Testing Webhooks

​From Dashboard

​Test Payload

​Integration Examples

​Slack

​PagerDuty

​Managing Webhooks

​List Webhooks

​Delete Webhook

​View Webhook Stats