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 TypeSeverityDescription
database.queryinfoTriggered when a SQL query is executed on a monitored database.
database.connectioninfoTriggered when a new connection is established to a monitored database.
database.disconnectinfoTriggered when a database connection is terminated.
security.threat_detectedcriticalTriggered when a potential security threat is identified, such as SQL injection attempts.
security.anomalywarningTriggered when unusual database activity patterns are detected.
security.privilege_escalationcriticalTriggered when a user attempts or succeeds in escalating their database privileges.
policy.violationwarningTriggered when a database operation violates a configured audit policy.
policy.matchinfoTriggered when a database operation matches a policy rule without violation.
data.sensitive_accesswarningTriggered when sensitive or classified data is accessed.
data.exportwarningTriggered when large amounts of data are exported or extracted.
user.login_failedwarningTriggered when a database login attempt fails.
user.login_successinfoTriggered 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

ParameterTypeDescription
typestringFilter by event type. Supports wildcards (e.g., security.*)
severitystringFilter by severity: info, warning, critical
database_idstringFilter events for a specific database
start_dateISO 8601Start of date range for filtering events
end_dateISO 8601End of date range for filtering events
userstringFilter by database user who triggered the event
source_ipstringFilter by source IP address
limitintegerNumber of events to return (default: 50, max: 1000)
pageintegerPage 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 AccountContact Sales