Alert Rules & Webhooks

Alert rules fire a webhook notification when violation counts exceed a configurable threshold within a sliding time window. Use them to page your SOC team or post to Slack when policy violations spike.

Managing Alert Rules

Via the Dashboard

Navigate to Alert Rules in the sidebar. From there you can create, edit, enable/disable, and delete rules.

Via the API

# Create an alert rule
curl -X POST https://your-policy-engine/api/v1/organizations/<orgId>/alerts \
  -H "Authorization: Bearer <admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "PII spike",
    "ruleCategory": "pii",
    "thresholdCount": 10,
    "windowMinutes": 60,
    "webhookUrl": "https://hooks.slack.com/services/T.../B.../...",
    "enabled": true
  }'

Alert Rule Fields

Field	Type	Description
name	string	Human-readable label
ruleCategory	string	Filter to a specific rule category (pii, financial, health, credentials, custom); leave empty to match all categories
thresholdCount	integer (1–10000)	Number of violations that triggers the alert
windowMinutes	integer (1–10080)	Sliding window duration in minutes (max 7 days)
webhookUrl	string (URL)	HTTPS endpoint that receives the notification
enabled	boolean	Whether the rule is active

Webhook Payload

When a rule fires, BitDrip sends a POST to webhookUrl with:

{
  "alert": "PII spike",
  "organizationId": "org-uuid",
  "triggerCount": 12,
  "windowMinutes": 60,
  "ruleCategory": "pii",
  "triggeredAt": "2026-06-02T19:00:00.000Z"
}

The Content-Type is application/json. No signature header is currently added — restrict access to the webhook endpoint by IP or use a secret in the URL.

Slack Integration

Create an Incoming Webhook in Slack, then paste the URL into the webhookUrl field. The payload structure is compatible with Slack's generic webhook format via a Slack Workflow — or use a small adapter function to format the message.

PagerDuty Integration

Set webhookUrl to your PagerDuty Events v2 endpoint:

https://events.pagerduty.com/v2/enqueue

Set the alert rule webhook URL to your Events API integration URL. BitDrip posts the raw JSON payload; use a PagerDuty webhook transformation or intermediary to map it to the PagerDuty event schema.

Alternatively, configure PagerDuty routing directly in org settings (Settings → Integrations → PagerDuty) for automatic severity mapping based on the risk score.

OpsGenie Integration

Set webhookUrl to your OpsGenie API endpoint and configure the OpsGenie API key in Settings → Integrations → OpsGenie.

Security

Webhook URLs are encrypted at rest using AES-256-GCM with a per-org derived key. They are decrypted only when a rule fires or when listed by an org admin.

Webhook endpoints must resolve to public, non-RFC-1918 addresses — the SSRF guard rejects internal network targets.