API Reference

Webhooks

Receive real-time notifications when security events occur in your monitored databases. Integrate DB Audit alerts directly into your incident response workflows.

Overview

Webhooks allow you to receive HTTP POST requests to your server whenever specific events occur in DB Audit. This enables real-time integration with your existing security tools, SIEM systems, and incident response platforms.

Real-time

Events delivered within milliseconds of occurrence

Secure

HMAC signatures verify authenticity

Reliable

Automatic retries with exponential backoff

Creating a Webhook

API Request

curl -X POST "https://api.dbaudit.ai/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/dbaudit",
    "events": ["alert.created", "policy.violation", "audit.anomaly"],
    "description": "Production alert notifications",
    "active": true
  }'

Response

{
  "id": "wh_abc123xyz",
  "url": "https://yourapp.com/webhooks/dbaudit",
  "events": ["alert.created", "policy.violation", "audit.anomaly"],
  "description": "Production alert notifications",
  "active": true,
  "secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "created_at": "2024-01-15T10:00:00Z"
}

Important

The secret is only shown once when creating the webhook. Store it securely to verify incoming webhook signatures.

Event Types

Subscribe to specific event types to receive only the notifications relevant to your integration.

Event	Description
`alert.created` Alerts	Triggered when a new security alert is created based on policy violations.
`alert.resolved` Alerts	Triggered when an alert is marked as resolved or acknowledged.
`alert.escalated` Alerts	Triggered when an alert is escalated to a higher severity level.
`policy.violation` Policies	Triggered immediately when a database query violates an active policy.
`policy.updated` Policies	Triggered when an audit policy is created, modified, or deleted.
`database.connected` Databases	Triggered when a new database connection is successfully established.
`database.disconnected` Databases	Triggered when a monitored database connection is lost.
`database.error` Databases	Triggered when a database monitoring error occurs.
`audit.anomaly` Audit	Triggered when anomalous database activity is detected by ML models.
`audit.sensitive_access` Audit	Triggered when sensitive or classified data is accessed.
`report.generated` Reports	Triggered when a scheduled compliance report is generated.

Payload Structure

All webhook payloads follow a consistent structure. The data object contains event-specific information.

Example Payload

{
  "id": "evt_1a2b3c4d5e6f",
  "type": "alert.created",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "alert_id": "alt_xyz789",
    "severity": "high",
    "database_id": "db_abc123",
    "policy_id": "pol_def456",
    "query": "SELECT * FROM users WHERE role = 'admin'",
    "user": "db_user@company.com",
    "source_ip": "192.168.1.100",
    "message": "Unauthorized access to admin user records detected"
  }
}

HTTP Headers

Each webhook request includes the following headers:

X-DBaudit-Signature HMAC SHA-256 signature for payload verification

X-DBaudit-Event The event type (e.g., alert.created)

X-DBaudit-Delivery-ID Unique identifier for this delivery attempt

X-DBaudit-Timestamp Unix timestamp when the event was sent

Content-Type Always application/json

Signature Verification

Always verify webhook signatures to ensure requests are genuinely from DB Audit. The signature is computed using HMAC SHA-256 with your webhook secret.

Python

import hmac
import hashlib

def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
    """Verify the webhook signature to ensure authenticity."""
    expected = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(f"sha256={expected}", signature)

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

    if not verify_webhook_signature(payload, signature, WEBHOOK_SECRET):
        raise HTTPException(status_code=401, detail="Invalid signature")

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

Node.js

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(`sha256=${expected}`),
    Buffer.from(signature)
  );
}

// Express.js webhook handler
app.post('/webhooks/dbaudit', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-dbaudit-signature'] as string;

  if (!verifyWebhookSignature(req.body.toString(), signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  // Process the event...

  res.status(200).send('OK');
});

Retry Policy

If your endpoint returns a non-2xx response or times out, DB Audit will automatically retry delivery using exponential backoff.

# Webhook delivery attempts follow exponential backoff:
# Attempt 1: Immediate
# Attempt 2: 1 minute
# Attempt 3: 5 minutes
# Attempt 4: 30 minutes
# Attempt 5: 2 hours
# Attempt 6: 8 hours
# Attempt 7: 24 hours (final attempt)

# Your endpoint should return 2xx status code within 30 seconds
# to be considered successful.

Best Practice

Return a 200 response immediately after receiving the webhook, then process the event asynchronously. This prevents timeouts and ensures reliable delivery.

Managing Webhooks

Use the API to list, update, or delete your webhook configurations.

# List all webhooks
curl -X GET "https://api.dbaudit.ai/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get a specific webhook
curl -X GET "https://api.dbaudit.ai/v1/webhooks/wh_abc123xyz" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Update a webhook
curl -X PATCH "https://api.dbaudit.ai/v1/webhooks/wh_abc123xyz" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["alert.created", "alert.escalated"],
    "active": true
  }'

# Delete a webhook
curl -X DELETE "https://api.dbaudit.ai/v1/webhooks/wh_abc123xyz" \
  -H "Authorization: Bearer YOUR_API_KEY"

Testing Webhooks

Send test events to verify your webhook endpoint is configured correctly before going live.

# Send a test event to your webhook endpoint
curl -X POST "https://api.dbaudit.ai/v1/webhooks/wh_abc123xyz/test" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "alert.created"
  }'

Test events are marked with "test": true in the payload so you can distinguish them from real events.

Common Use Cases

SIEM Integration

Forward security alerts to Splunk, Elastic, or your preferred SIEM for centralized monitoring and correlation.

Slack/Teams Notifications

Send instant alerts to your security team's chat channels when critical policy violations occur.

Ticketing Systems

Automatically create tickets in Jira, ServiceNow, or PagerDuty when alerts require investigation.

Custom Automation

Trigger automated responses like blocking suspicious IPs or revoking database access based on detected threats.

Next Steps

Explore more API capabilities to build powerful integrations:

Authentication

Events API

Policies API

Start Receiving Real-time Alerts

Set up your first webhook and integrate DB Audit with your security workflows.

Configure Webhooks Contact Sales