Back to Documentation

Webhooks Integration

Send real-time database events to your custom endpoints for seamless integration with your infrastructure.

Overview

Webhooks allow DB24x7 to push real-time event data to your applications. Configure webhook endpoints to receive notifications about database events, alerts, optimizations, and more. Build custom workflows, integrate with internal tools, or trigger automation based on database state changes.

Real-time Events

Receive HTTP POST requests immediately when events occur

Secure Delivery

HMAC signature verification for request authenticity

Automatic Retries

Exponential backoff retry logic for failed deliveries

Creating Webhook Endpoints

Step 1: Configure in Dashboard

  1. Navigate to DB24x7 Dashboard → Settings → Integrations → Webhooks
  2. Click Add Webhook
  3. Enter your webhook URL (must be HTTPS in production)
  4. Select the event types you want to receive
  5. Copy the generated Signing Secret for signature verification
  6. Click Save to activate the webhook

Step 2: Implement Your Endpoint

Your endpoint should accept HTTP POST requests and return a 200 status code:

Node.js / Express Example

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.DB24X7_WEBHOOK_SECRET;

// Verify webhook signature
function verifySignature(payload, signature) {
  const hmac = crypto.createHmac('sha256', WEBHOOK_SECRET);
  const digest = 'sha256=' + hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(digest));
}

app.post('/webhooks/db24x7', (req, res) => {
  const signature = req.headers['x-db24x7-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifySignature(payload, signature)) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.body;
  console.log('Received event:', event.type);

  // Process event
  switch (event.type) {
    case 'alert.critical':
      handleCriticalAlert(event.data);
      break;
    case 'optimization.completed':
      handleOptimizationCompleted(event.data);
      break;
    case 'database.health_check':
      handleHealthCheck(event.data);
      break;
    default:
      console.log('Unhandled event type:', event.type);
  }

  res.status(200).json({ received: true });
});

app.listen(3000);

Python / Flask Example

from flask import Flask, request, jsonify
import hmac
import hashlib
import os

app = Flask(__name__)
WEBHOOK_SECRET = os.environ.get('DB24X7_WEBHOOK_SECRET')

def verify_signature(payload, signature):
    expected_signature = 'sha256=' + hmac.new(
        WEBHOOK_SECRET.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected_signature, signature)

@app.route('/webhooks/db24x7', methods=['POST'])
def webhook():
    signature = request.headers.get('X-DB24x7-Signature')
    payload = request.get_data(as_text=True)

    if not verify_signature(payload, signature):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.json
    event_type = event.get('type')

    if event_type == 'alert.critical':
        handle_critical_alert(event['data'])
    elif event_type == 'optimization.completed':
        handle_optimization_completed(event['data'])
    elif event_type == 'database.health_check':
        handle_health_check(event['data'])

    return jsonify({'received': True}), 200

if __name__ == '__main__':
    app.run(port=3000)

Payload Format

All webhook payloads follow a consistent JSON structure:

Base Payload Structure

{
  "id": "evt_1a2b3c4d5e6f7g8h",
  "type": "alert.critical",
  "created_at": "2026-02-07T10:30:00Z",
  "data": {
    // Event-specific data
  },
  "account_id": "acc_xyz123",
  "environment": "production"
}

Example: Critical Alert Event

{
  "id": "evt_1a2b3c4d5e6f7g8h",
  "type": "alert.critical",
  "created_at": "2026-02-07T10:30:00Z",
  "data": {
    "alert_id": "alert_abc123",
    "database": "production-postgres-01",
    "severity": "critical",
    "category": "performance",
    "metric": "cpu_usage",
    "current_value": 95.3,
    "threshold": 80.0,
    "duration_seconds": 300,
    "message": "Database CPU usage has exceeded threshold for 5 minutes",
    "affected_resources": {
      "queries": 23,
      "connections": 150
    },
    "suggested_actions": [
      {
        "action": "terminate_query",
        "query_id": "12345",
        "description": "Terminate long-running query consuming 45% CPU"
      }
    ],
    "dashboard_url": "https://app.db24x7.com/alerts/alert_abc123"
  },
  "account_id": "acc_xyz123",
  "environment": "production"
}

Example: Optimization Completed Event

{
  "id": "evt_9z8y7x6w5v4u3t2s",
  "type": "optimization.completed",
  "created_at": "2026-02-07T11:15:00Z",
  "data": {
    "optimization_id": "opt_def456",
    "database": "production-postgres-01",
    "query_id": "query_789",
    "optimization_type": "index_suggestion",
    "improvements": {
      "execution_time_before_ms": 2500,
      "execution_time_after_ms": 45,
      "improvement_percentage": 98.2,
      "scanned_rows_before": 1000000,
      "scanned_rows_after": 1
    },
    "changes_applied": [
      {
        "type": "create_index",
        "table": "users",
        "columns": ["email", "created_at"],
        "index_name": "idx_users_email_created_at"
      }
    ],
    "dashboard_url": "https://app.db24x7.com/optimizations/opt_def456"
  },
  "account_id": "acc_xyz123",
  "environment": "production"
}

Available Event Types

alert.criticalAlerts

Triggered when a critical database alert is raised (CPU, memory, disk, connections)

alert.warningAlerts

Triggered when a warning-level alert is raised

alert.resolvedAlerts

Triggered when an alert is automatically or manually resolved

optimization.completedOptimization

Triggered when the AI DBA completes a query or schema optimization

optimization.suggestedOptimization

Triggered when the AI DBA suggests an optimization pending approval

database.health_checkMonitoring

Triggered on scheduled health check completion with current metrics

database.connection_failedMonitoring

Triggered when DB24x7 loses connection to a monitored database

backup.completedBackup

Triggered when a scheduled or manual backup completes successfully

backup.failedBackup

Triggered when a backup operation fails with error details

maintenance.startedMaintenance

Triggered when a maintenance window begins

maintenance.completedMaintenance

Triggered when a maintenance window ends

Security & Verification

HMAC Signature Verification

Every webhook request includes an X-DB24x7-Signature header containing an HMAC SHA-256 signature. Always verify this signature before processing webhook data.

Security Warning

Never process webhook requests without signature verification. This could allow malicious actors to trigger unauthorized actions in your system.

Signature Format

sha256=<hmac_hex_digest>

Verification Steps

  1. Extract the signature from the X-DB24x7-Signature header
  2. Compute HMAC SHA-256 of the raw request body using your webhook secret
  3. Compare the computed signature with the received signature using timing-safe comparison
  4. Only process the webhook if signatures match

Additional Security Headers

X-DB24x7-Event-IDUnique event identifier for idempotency
X-DB24x7-Delivery-IDUnique delivery attempt ID for debugging
X-DB24x7-TimestampUnix timestamp of the webhook generation

IP Allowlist (Optional)

For additional security, you can restrict webhook requests to DB24x7's IP addresses:

52.203.45.67
52.203.45.68
52.203.45.69
52.203.45.70

Note: IP addresses may change. Subscribe to our webhook IP changelog for updates.

Retry Logic

If your endpoint fails to respond with a 2xx status code, DB24x7 automatically retries delivery using exponential backoff.

Retry Schedule

Attempt 1Immediate
Attempt 2After 30 seconds
Attempt 3After 5 minutes
Attempt 4After 30 minutes
Attempt 5After 2 hours
Attempt 6 (Final)After 12 hours

Handling Retries

Idempotency Best Practice

Use the X-DB24x7-Event-ID header to track processed events and ensure idempotent handling:

// Store processed event IDs
const processedEvents = new Set();

app.post('/webhooks/db24x7', (req, res) => {
  const eventId = req.headers['x-db24x7-event-id'];

  if (processedEvents.has(eventId)) {
    // Already processed, return success
    return res.status(200).json({ received: true });
  }

  // Process event...
  processEvent(req.body);

  // Mark as processed
  processedEvents.add(eventId);
  res.status(200).json({ received: true });
});

Monitoring Failed Deliveries

View failed webhook deliveries in the DB24x7 dashboard:

Settings → Integrations → Webhooks → [Your Webhook] → Delivery History

You can manually retry failed deliveries or disable the webhook if issues persist.

Testing Your Webhook

Using the Dashboard

  1. Navigate to your webhook configuration in the dashboard
  2. Click the "Send Test Event" button
  3. Select an event type to test
  4. DB24x7 will send a sample payload to your endpoint
  5. Check the delivery status and response in the dashboard

Local Testing with ngrok

For local development, use ngrok to expose your local endpoint:

# Start your local server
npm start  # or python app.py

# In another terminal, start ngrok
ngrok http 3000

# Use the ngrok HTTPS URL in DB24x7 webhook configuration
# Example: https://abc123.ngrok.io/webhooks/db24x7

Best Practices

Recommendations

  • Always verify HMAC signatures before processing
  • Implement idempotency using event IDs
  • Return 2xx status codes quickly (process async if needed)
  • Log all webhook receipts for debugging
  • Use HTTPS endpoints in production
  • Set up monitoring for webhook endpoint uptime
  • Handle all event types gracefully (even unknown ones)

Common Pitfalls

  • Not verifying signatures (major security risk)
  • Processing webhooks synchronously causing timeouts
  • Not handling duplicate events (lack of idempotency)
  • Returning error codes for successfully received events
  • Using HTTP instead of HTTPS in production

Next Steps