API Reference

Events API

Access real-time audit events from your monitored databases. Query historical events, set up webhooks, or stream events as they happen.

Overview

The Events API provides programmatic access to all audit events captured by DB Audit. Events are generated when database activity matches your monitoring rules, security threats are detected, or policy violations occur.

Query Events

Search and filter historical events with powerful query parameters.

Webhooks

Receive real-time notifications when events occur.

Event Streaming

Stream events in real-time using Server-Sent Events.

Event Types

DB Audit generates events for various database activities and security incidents. Each event includes a type identifier, severity level, and detailed context.

Event Type Severity Description
database.query info Triggered when a SQL query is executed on a monitored database.
database.connection info Triggered when a new connection is established to a monitored database.
database.disconnect info Triggered when a database connection is terminated.
security.threat_detected critical Triggered when a potential security threat is identified, such as SQL injection attempts.
security.anomaly warning Triggered when unusual database activity patterns are detected.
security.privilege_escalation critical Triggered when a user attempts or succeeds in escalating their database privileges.
policy.violation warning Triggered when a database operation violates a configured audit policy.
policy.match info Triggered when a database operation matches a policy rule without violation.
data.sensitive_access warning Triggered when sensitive or classified data is accessed.
data.export warning Triggered when large amounts of data are exported or extracted.
user.login_failed warning Triggered when a database login attempt fails.
user.login_success info Triggered when a user successfully authenticates to a database.
GET /v1/events

List Events

Retrieve a paginated list of audit events. Use query parameters to filter by type, severity, date range, and more.

Query Parameters

Parameter Type Description
type string Filter by event type. Supports wildcards (e.g., security.*)
severity string Filter by severity: info, warning, critical
database_id string Filter events for a specific database
start_date ISO 8601 Start of date range for filtering events
end_date ISO 8601 End of date range for filtering events
user string Filter by database user who triggered the event
source_ip string Filter by source IP address
limit integer Number of events to return (default: 50, max: 1000)
page integer Page number for pagination

Example Request

# List recent events
curl -X GET "https://api.dbaudit.ai/v1/events" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Response
{
  "events": [
    {
      "id": "evt_1a2b3c4d5e6f",
      "type": "security.threat_detected",
      "severity": "critical",
      "database_id": "db_abc123",
      "timestamp": "2025-01-15T14:32:18Z",
      "details": {
        "threat_type": "sql_injection",
        "query": "SELECT * FROM users WHERE id = '1' OR '1'='1'",
        "source_ip": "192.168.1.100",
        "user": "app_user"
      }
    }
  ],
  "pagination": {
    "total": 1542,
    "page": 1,
    "per_page": 50
  }
}

Filtering Events

Use query parameters to narrow down results. Wildcards are supported for event types. 

# Filter events by type and severity
curl -X GET "https://api.dbaudit.ai/v1/events?type=security.*&severity=critical&limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter by date range
curl -X GET "https://api.dbaudit.ai/v1/events?\
  start_date=2025-01-01T00:00:00Z&\
  end_date=2025-01-31T23:59:59Z&\
  database_id=db_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"
GET /v1/events/:event_id

Get Event

Retrieve detailed information about a specific event, including full context, related events, and policy matches. 

# Get a specific event by ID
curl -X GET "https://api.dbaudit.ai/v1/events/evt_1a2b3c4d5e6f" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response includes full event details
{
  "id": "evt_1a2b3c4d5e6f",
  "type": "security.threat_detected",
  "severity": "critical",
  "database_id": "db_abc123",
  "database_name": "production_users",
  "timestamp": "2025-01-15T14:32:18Z",
  "processed_at": "2025-01-15T14:32:19Z",
  "details": {
    "threat_type": "sql_injection",
    "query": "SELECT * FROM users WHERE id = '1' OR '1'='1'",
    "source_ip": "192.168.1.100",
    "user": "app_user",
    "session_id": "sess_xyz789",
    "client_application": "web_app_v2"
  },
  "context": {
    "policy_id": "pol_security_001",
    "rule_id": "rule_sqli_detect",
    "risk_score": 95
  },
  "related_events": ["evt_related1", "evt_related2"]
}

Webhooks

Webhooks allow you to receive real-time notifications when events occur. Configure endpoints to receive HTTP POST requests for specific event types.

Create a Webhook

# Create a webhook endpoint
curl -X POST "https://api.dbaudit.ai/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/dbaudit",
    "events": ["security.*", "policy.violation"],
    "secret": "whsec_your_signing_secret"
  }'

# Response
{
  "id": "wh_abc123",
  "url": "https://your-app.com/webhooks/dbaudit",
  "events": ["security.*", "policy.violation"],
  "status": "active",
  "created_at": "2025-01-15T10:00:00Z"
}

Webhook Payload

When an event matches your webhook subscription, we'll send a POST request to your endpoint with the following structure: 

# Webhook payload structure
POST /webhooks/dbaudit HTTP/1.1
Host: your-app.com
Content-Type: application/json
X-DBaudit-Signature: sha256=abc123...
X-DBaudit-Timestamp: 1705329138

{
  "id": "evt_1a2b3c4d5e6f",
  "type": "security.threat_detected",
  "created": "2025-01-15T14:32:18Z",
  "data": {
    "database_id": "db_abc123",
    "severity": "critical",
    "threat_type": "sql_injection",
    "source_ip": "192.168.1.100"
  }
}

Verify Webhook Signatures

Always verify the X-DBaudit-Signature header to ensure webhooks are authentic and haven't been tampered with.

Signature Verification

import hmac
import hashlib

def verify_webhook(payload, signature, timestamp, secret):
    """Verify the webhook signature to ensure authenticity."""
    # Construct the signed payload
    signed_payload = f"{timestamp}.{payload}"

    # Compute expected signature
    expected_sig = hmac.new(
        secret.encode('utf-8'),
        signed_payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    # Compare signatures
    return hmac.compare_digest(f"sha256={expected_sig}", signature)

Real-Time Streaming

For applications that need real-time event data, use our Server-Sent Events (SSE) endpoint. Events are pushed to your client as they occur with minimal latency.

GET /v1/events/stream 
# Stream events in real-time using SSE
curl -N -X GET "https://api.dbaudit.ai/v1/events/stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream"

# Events are delivered as Server-Sent Events
event: security.threat_detected
data: {"id":"evt_1a2b3c4d5e6f","type":"security.threat_detected",...}

event: database.query
data: {"id":"evt_2b3c4d5e6f7g","type":"database.query",...}

Low Latency

Events are delivered within milliseconds of occurrence.

Auto Reconnect

Use the Last-Event-ID header to resume from where you left off.

Rate Limits

The Events API has the following rate limits to ensure fair usage:

List Events

GET /v1/events

1000 requests/min

Get Event

GET /v1/events/:id

2000 requests/min

Event Stream

GET /v1/events/stream

10 concurrent connections

Related Resources

Learn more about working with events and integrating DB Audit into your security workflow:

API Authentication
Alerting Configuration
Audit Policies

Start Monitoring Events

Set up event monitoring for your databases and get real-time visibility into database activity.

Create Free Account Contact Sales