API Reference

All Notification plugin endpoints use the base path /_plugins/_notifications.

Notification Configs

Create a Notification Config

Creates a new notification channel configuration.

Request body:

{
  "config": {
    "name": "<config-name>",
    "description": "<config-description>",
    "config_type": "<channel-type>",
    "is_enabled": true,
    "<channel-type>": {
      // channel-specific fields
    }
  }
}

Slack example:

{
  "config": {
    "name": "my-slack-channel",
    "description": "Slack notifications for alerts",
    "config_type": "slack",
    "is_enabled": true,
    "slack": {
      "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX"
    }
  }
}

Email example (with SMTP account):

{
  "config": {
    "name": "my-email-channel",
    "description": "Email alerts via SMTP",
    "config_type": "email",
    "is_enabled": true,
    "email": {
      "email_account_id": "<smtp-account-config-id>",
      "recipient_list": [
        { "recipient": "alerts@example.com" }
      ],
      "email_group_id_list": []
    }
  }
}

SMTP account example:

{
  "config": {
    "name": "my-smtp-account",
    "description": "Corporate SMTP server",
    "config_type": "smtp_account",
    "is_enabled": true,
    "smtp_account": {
      "host": "smtp.example.com",
      "port": 587,
      "method": "start_tls",
      "from_address": "noreply@example.com"
    }
  }
}

Webhook example:

{
  "config": {
    "name": "my-custom-webhook",
    "description": "Custom webhook for incident system",
    "config_type": "webhook",
    "is_enabled": true,
    "webhook": {
      "url": "https://incident.example.com/api/alert",
      "header_params": {
        "Content-Type": "application/json"
      },
      "method": "POST"
    }
  }
}

Microsoft Teams example:

{
  "config": {
    "name": "my-teams-channel",
    "description": "Teams notifications",
    "config_type": "microsoft_teams",
    "is_enabled": true,
    "microsoft_teams": {
      "url": "https://outlook.office.com/webhook/..."
    }
  }
}

SNS example:

{
  "config": {
    "name": "my-sns-topic",
    "description": "SNS notifications",
    "config_type": "sns",
    "is_enabled": true,
    "sns": {
      "topic_arn": "arn:aws:sns:us-east-1:123456789012:my-topic",
      "role_arn": "arn:aws:iam::123456789012:role/sns-publish-role"
    }
  }
}

Response:

{
  "config_id": "<generated-config-id>"
}

Update a Notification Config

Updates an existing notification channel configuration.

Request body: Same structure as create. All fields in the config object are replaced.

{
  "config": {
    "name": "updated-slack-channel",
    "description": "Updated description",
    "config_type": "slack",
    "is_enabled": true,
    "slack": {
      "url": "https://hooks.slack.com/services/T00000000/B00000000/YYYYYYYY"
    }
  }
}

Response:

{
  "config_id": "<config-id>"
}

Get a Notification Config

Retrieves a specific notification configuration by ID.

Response:

{
  "config_list": [
    {
      "config_id": "<config-id>",
      "last_updated_time_ms": 1234567890,
      "created_time_ms": 1234567890,
      "config": {
        "name": "my-slack-channel",
        "description": "Slack notifications for alerts",
        "config_type": "slack",
        "is_enabled": true,
        "slack": {
          "url": "https://hooks.slack.com/services/..."
        }
      }
    }
  ],
  "total_hits": 1
}

List Notification Configs

Retrieves notification configurations with filtering, sorting, and pagination.

Query parameters:

Example:

curl -sk -u admin:admin \
  "https://localhost:9200/_plugins/_notifications/configs?config_type=slack&max_items=10&sort_order=desc"

Delete a Notification Config

Deletes one or more notification configurations.

Or for bulk delete:

Response:

{
  "delete_response_list": {
    "<config-id>": "OK"
  }
}

Channels

List Notification Channels

Returns a simplified list of all configured notification channels (ID, name, type, and enabled status).

Response:

{
  "channel_list": [
    {
      "config_id": "<id>",
      "name": "my-slack-channel",
      "config_type": "slack",
      "is_enabled": true
    }
  ],
  "total_hits": 1
}

Features

Get Plugin Features

Returns the notification features and allowed config types supported by the plugin.

Response:

{
  "allowed_config_type_list": [
    "slack",
    "chime",
    "microsoft_teams",
    "webhook",
    "email",
    "sns",
    "ses_account",
    "smtp_account",
    "email_group"
  ],
  "plugin_features": {
    "tooltip_support": "true"
  }
}

Test Notifications

Send Test Notification

Sends a test notification to a configured channel to validate the configuration.

Note: GET is also supported for backwards compatibility but is deprecated and will be removed in a future major version.

Example:

curl -sk -u admin:admin -X POST \
  "https://localhost:9200/_plugins/_notifications/feature/test/<config-id>"

Response:

{
  "status_list": [
    {
      "config_id": "<config-id>",
      "config_type": "slack",
      "config_name": "my-slack-channel",
      "delivery_status": {
        "status_code": "200",
        "status_text": "ok"
      }
    }
  ]
}

Stats

Get Plugin Stats

Returns internal plugin metrics and counters.

Response: A JSON object with flattened metric counters including:

• Request totals and interval counts for each API operation (create, update, delete, info, features, channels, send test).

Summary Table