> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wazuh/wazuh-dashboard-plugins/llms.txt
> Use this file to discover all available pages before exploring further.

# Notifications and Alerting

> Configure notification channels and alerting monitors for Wazuh Dashboard

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 Type | Default ID |
| - | - |
| Slack | `wazuh-slack` |
| PagerDuty | `wazuh-pagerduty` |
| Jira | `wazuh-jira` |
| Shuffle | `wazuh-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):**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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):**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "period": {
    "interval": 1,
    "unit": "MINUTES"
  }
}
```

**Data Source:**

```json theme={null}
{
  "indices": ["wazuh-events*"]
}
```

**Query Example (Match All):**

```json theme={null}
{
  "size": 100,
  "query": {
    "match_all": {}
  }
}
```

**Query Example (Filtered):**

```json theme={null}
{
  "size": 100,
  "query": {
    "bool": {
      "filter": [
        {
          "range": {
            "@timestamp": {
              "gte": "now-5m",
              "lte": "now"
            }
          }
        },
        {
          "term": {
            "rule.level": 10
          }
        }
      ]
    }
  }
}
```

### Trigger Configuration

**Condition Script:**

```javascript theme={null}
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:**

```json theme={null}
{
  "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:**

```html theme={null}
<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

## Related Topics

* [Health Check System](/configuration/health-check)
* [Plugin Settings](/configuration/settings)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.