Skip to main content
The Wazuh Dashboard integrates with OpenSearch Alerting and Notifications plugins to provide flexible alerting capabilities and notification delivery to external systems.

​
Overview

The notification and alerting system allows you to:
  • Configure notification channels for external integrations
  • Create alerting monitors that detect security events
  • Send notifications to Slack, PagerDuty, Jira, and other services
  • Automate incident response workflows
  • Customize alert messages and severity levels

​
Architecture

The system consists of two main components:

​
Notification Channels

Notification channels define the destination and delivery method for alerts. Supported channel types include:
  • Slack - Send messages to Slack channels
  • PagerDuty - Create incidents in PagerDuty
  • Jira - Create issues in Jira projects
  • Shuffle - Trigger automation workflows
  • Webhook - Send HTTP POST requests to custom endpoints
  • Email - Send email notifications (requires SMTP configuration)
  • Amazon SNS - Publish to Amazon Simple Notification Service topics
  • Custom Webhook - Advanced webhook configurations with custom payloads

​
Alerting Monitors

Monitors continuously evaluate queries against Wazuh data and trigger notifications when conditions are met. The Dashboard health check system can automatically create sample monitors for quick integration testing.

​
Notification Channels

​
Channel Configuration

Notification channels are configured through the OpenSearch Notifications plugin. The Wazuh Dashboard health check system can automatically create default channels for common integrations.

​
Default Channel IDs

The health check system creates channels with predefined IDs for easy reference:
Channel TypeDefault ID
Slackwazuh-slack
PagerDutywazuh-pagerduty
Jirawazuh-jira
Shufflewazuh-shuffle

​
Creating Notification Channels

Channels can be created through:
  1. Dashboard UI: Navigate to OpenSearch Dashboards > Notifications
  2. API: Use the Notifications plugin REST API
  3. Health Check: Automatic creation during Dashboard initialization

​
Configuring Integrations

​
Slack Integration

Requirements:
  • Slack workspace with admin access
  • Incoming webhook URL from Slack
Configuration:
  1. Create an incoming webhook in Slack:
    • Navigate to Slack API > Incoming Webhooks
    • Choose a channel for notifications
    • Copy the webhook URL
  2. Configure the notification channel:
Channel Name: Wazuh Slack Type: Slack Webhook URL: https://hooks.slack.com/services/YOUR/WEBHOOK/URL Message Template Example: 
Sample Slack alert. Monitor: {{ctx.monitor.name}}. Trigger: {{ctx.trigger.name}}. Matches: {{ctx.results.0.hits.total.value}}.

​
PagerDuty Integration

Requirements:
  • PagerDuty account
  • Integration key (routing key) from PagerDuty
Configuration:
  1. Create an integration in PagerDuty:
    • Navigate to Services > Select Service > Integrations
    • Add Integration > Events API V2
    • Copy the integration key
  2. Configure the notification channel:
Channel Name: Wazuh PagerDuty Type: Custom Webhook Webhook URL: https://events.pagerduty.com/v2/enqueue Message Template (JSON): 
{
  "routing_key": "YOUR_INTEGRATION_KEY",
  "event_action": "trigger",
  "payload": {
    "summary": "Wazuh Alert: {{ctx.monitor.name}}",
    "severity": "critical",
    "source": "Wazuh Dashboard Alerting",
    "custom_details": {
      "monitor": "{{ctx.monitor.name}}",
      "trigger": "{{ctx.trigger.name}}",
      "matches": "{{ctx.results.0.hits.total.value}}"
    }
  }
}
Headers: 
{
  "Content-Type": "application/json"
}

​
Jira Integration

Requirements:
  • Jira instance (Cloud or Server)
  • API token or password
  • Project key for issue creation
Configuration:
  1. Generate API token in Jira:
    • Navigate to Account Settings > Security > API Tokens
    • Create and copy the API token
  2. Configure the notification channel:
Channel Name: Wazuh Jira Type: Custom Webhook Webhook URL: https://your-domain.atlassian.net/rest/api/3/issue Authentication: Basic Auth
  • Username: Your Jira email
  • Password: API token
Message Template (JSON): 
{
  "fields": {
    "project": {
      "key": "SEC"
    },
    "summary": "Wazuh Alert: {{ctx.monitor.name}}",
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "Alert triggered: {{ctx.trigger.name}}. Matches: {{ctx.results.0.hits.total.value}}"
            }
          ]
        }
      ]
    },
    "issuetype": {
      "name": "Task"
    }
  }
}
Headers: 
{
  "Content-Type": "application/json"
}

​
Shuffle Integration

Requirements:
  • Shuffle instance (cloud or on-premise)
  • Webhook URL from Shuffle workflow
Configuration:
  1. Create a webhook trigger in Shuffle:
    • Create or edit a workflow
    • Add a Webhook trigger
    • Copy the webhook URL
  2. Configure the notification channel:
Channel Name: Wazuh Shuffle Type: Webhook Webhook URL: https://shuffler.io/api/v1/hooks/YOUR_WEBHOOK_ID Message Template: 
Sample Shuffle alert. Monitor: {{ctx.monitor.name}}. Trigger: {{ctx.trigger.name}}. Matches: {{ctx.results.0.hits.total.value}}.

​
Alerting Monitors

​
Monitor Components

An alerting monitor consists of:
  1. Schedule: How frequently the monitor runs
  2. Data Source: The index pattern to query
  3. Query: The search query to execute
  4. Trigger: Conditions that activate the alert
  5. Actions: Notifications to send when triggered

​
Sample Monitors

The Dashboard health check system can create sample monitors for testing integrations. These monitors query Wazuh events and trigger notifications based on configurable conditions.

​
Monitor Configuration

Monitor Schedule: 
{
  "period": {
    "interval": 1,
    "unit": "MINUTES"
  }
}
Data Source: 
{
  "indices": ["wazuh-events*"]
}
Query Example (Match All): 
{
  "size": 100,
  "query": {
    "match_all": {}
  }
}
Query Example (Filtered): 
{
  "size": 100,
  "query": {
    "bool": {
      "filter": [
        {
          "range": {
            "@timestamp": {
              "gte": "now-5m",
              "lte": "now"
            }
          }
        },
        {
          "term": {
            "rule.level": 10
          }
        }
      ]
    }
  }
}

​
Trigger Configuration

Condition Script: 
return ctx.results[0].hits.total.value > 0
Severity Levels:
  • 1 - Critical
  • 2 - High
  • 3 - Medium
  • 4 - Low
  • 5 - Informational

​
Action Configuration

Subject Template: 
Wazuh Alert: {{ctx.monitor.name}}
Message Template (Mustache): 
Monitor: {{ctx.monitor.name}}
Trigger: {{ctx.trigger.name}}
Severity: {{ctx.trigger.severity}}
Matches: {{ctx.results.0.hits.total.value}}

Alert details: Review the Wazuh Dashboard for more information.

​
Creating Monitors via API

Use the OpenSearch Alerting API to create monitors programmatically: Endpoint: 
POST /_plugins/_alerting/monitors
Example Request Body: 
{
  "type": "monitor",
  "name": "High Severity Events",
  "enabled": true,
  "schedule": {
    "period": {
      "interval": 5,
      "unit": "MINUTES"
    }
  },
  "inputs": [
    {
      "search": {
        "indices": ["wazuh-events*"],
        "query": {
          "size": 0,
          "query": {
            "bool": {
              "filter": [
                {
                  "range": {
                    "@timestamp": {
                      "gte": "now-5m"
                    }
                  }
                },
                {
                  "range": {
                    "rule.level": {
                      "gte": 10
                    }
                  }
                }
              ]
            }
          }
        }
      }
    }
  ],
  "triggers": [
    {
      "name": "High severity events detected",
      "severity": "1",
      "condition": {
        "script": {
          "lang": "painless",
          "source": "return ctx.results[0].hits.total.value > 0"
        }
      },
      "actions": [
        {
          "name": "Send Slack notification",
          "destination_id": "wazuh-slack",
          "subject_template": {
            "lang": "mustache",
            "source": "High Severity Alert"
          },
          "message_template": {
            "lang": "mustache",
            "source": "High severity events detected. Count: {{ctx.results.0.hits.total.value}}"
          }
        }
      ]
    }
  ]
}

​
Message Templates

Message templates use Mustache syntax to include dynamic content from the alert context.

​
Available Context Variables

Monitor Information:
  • {{ctx.monitor.name}} - Monitor name
  • {{ctx.monitor.type}} - Monitor type
  • {{ctx.monitor.enabled}} - Monitor enabled status
Trigger Information:
  • {{ctx.trigger.name}} - Trigger name
  • {{ctx.trigger.severity}} - Severity level
Query Results:
  • {{ctx.results.0.hits.total.value}} - Total matches
  • {{ctx.results.0.hits.hits}} - Result documents (array)
Time Information:
  • {{ctx.periodStart}} - Query period start time
  • {{ctx.periodEnd}} - Query period end time

​
Template Examples

Detailed Slack Message: 
:warning: *Wazuh Alert*
*Monitor:* {{ctx.monitor.name}}
*Trigger:* {{ctx.trigger.name}}
*Severity:* Level {{ctx.trigger.severity}}
*Matches:* {{ctx.results.0.hits.total.value}} events
*Period:* {{ctx.periodStart}} to {{ctx.periodEnd}}

Review the Wazuh Dashboard for details.
Formatted Email: 
<h2>Wazuh Security Alert</h2>
<p><strong>Monitor:</strong> {{ctx.monitor.name}}</p>
<p><strong>Trigger:</strong> {{ctx.trigger.name}}</p>
<p><strong>Severity:</strong> {{ctx.trigger.severity}}</p>
<p><strong>Events Detected:</strong> {{ctx.results.0.hits.total.value}}</p>
<p>Please review the Wazuh Dashboard for additional details.</p>

​
Health Check Integration

The Dashboard health check system can automatically create notification channels and sample monitors during initialization.

​
Automatic Channel Creation

The health check creates default notification channels with placeholder configurations. After initial creation, update the channels with actual credentials:
  1. Navigate to OpenSearch Dashboards > Notifications
  2. Edit each notification channel
  3. Update webhook URLs, API keys, and other credentials
  4. Test the notification to verify configuration

​
Automatic Monitor Creation

Sample monitors are created only if the corresponding notification channels exist. This prevents monitors from being created without valid destinations. Sample Monitors Created:
  • Sample: Slack
  • Sample: PagerDuty
  • Sample: Jira
  • Sample: Shuffle

​
Best Practices

​
Monitor Design

  1. Specific Queries: Create focused queries that target specific event types
  2. Appropriate Thresholds: Set thresholds that reduce false positives
  3. Reasonable Frequency: Balance detection speed with system load
  4. Clear Naming: Use descriptive names that explain the monitor’s purpose
  5. Document Monitors: Include descriptions explaining trigger conditions

​
Notification Management

  1. Rate Limiting: Implement notification throttling to prevent alert fatigue
  2. Severity-Based Routing: Send critical alerts to different channels than informational alerts
  3. Message Clarity: Include enough context in messages for actionable responses
  4. Test Notifications: Verify notifications are delivered before enabling production monitors
  5. Secure Credentials: Protect webhook URLs and API tokens

​
Performance Considerations

  1. Limit Query Scope: Use time-based filters to reduce data volume
  2. Optimize Schedules: Avoid running many monitors simultaneously
  3. Monitor Count: Balance monitoring coverage with system resources
  4. Result Size: Limit the number of documents returned in queries

​
Troubleshooting

​
Notifications Not Delivered

Solutions:
  1. Verify the notification channel configuration is correct
  2. Test the webhook URL independently
  3. Check authentication credentials
  4. Review OpenSearch logs for delivery errors
  5. Verify network connectivity to external services

​
Monitor Not Triggering

Solutions:
  1. Verify the query returns results when run manually
  2. Check the trigger condition script syntax
  3. Review monitor schedule and last execution time
  4. Ensure the monitor is enabled
  5. Check index patterns match actual indices

​
Invalid Message Templates

Solutions:
  1. Verify Mustache syntax is correct
  2. Check that referenced context variables exist
  3. Test templates with sample data
  4. Review logs for template rendering errors