Notifications API

Use the Notifications REST API to programmatically create, retrieve, update, and delete notification configurations and to send test messages. Defining channels through the API lets you version and reuse your channel definitions.

A notification configuration is one of the following types:

• A channel that receives notifications: slack, chime, microsoft_teams, webhook, email, or sns.
• An email sender that an email channel uses to send messages: smtp_account or ses_account.
• An email recipient group that an email channel sends messages to: email_group.

Table of contents

1. List supported channel configurations
   1. Endpoints
   2. Example request
   3. Example response
   4. Response body fields
2. List all notification channels
   1. Endpoints
   2. Example request
   3. Example response
3. List all notification configurations
   1. Endpoints
   2. Query parameters
   3. Example request
   4. Example response
   5. Response body fields
4. Create channel configuration
   1. Endpoints
   2. Request body fields
   3. Example: Creating a Slack channel
   4. Example: Creating a custom webhook channel
   5. Example: Creating an email channel
   6. Example: Creating an Amazon SNS channel
   7. Example response
5. Get channel configuration
   1. Endpoints
   2. Path parameters
   3. Example request
   4. Example response
6. Update channel configuration
   1. Endpoints
   2. Path parameters
   3. Example request
   4. Example response
7. Delete channel configuration
   1. Endpoints
   2. Path parameters
   3. Query parameters
   4. Example request
   5. Example response
   6. Example: Deleting multiple configurations
8. Send test notification
   1. Endpoints
   2. Path parameters
   3. Example request
   4. Example response
   5. Response body fields

List supported channel configurations

To retrieve a list of all supported notification configuration types, send a GET request to the features resource.

Endpoints

GET /_plugins/_notifications/features

Example request

GET /_plugins/_notifications/features

Example response

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

Response body fields

The following table lists all response body fields.

List all notification channels

To retrieve a list of all notification channels, send a GET request to the channels resource. The response contains configurations of the slack, chime, microsoft_teams, webhook, email, and sns types. Email senders and email recipient groups are not channels, so the response omits them. This endpoint does not accept query parameters.

Endpoints

GET /_plugins/_notifications/channels

Example request

GET /_plugins/_notifications/channels

Example response

{
  "start_index" : 0,
  "total_hits" : 2,
  "total_hit_relation" : "eq",
  "channel_list" : [
    {
      "config_id" : "sample-id",
      "name" : "Sample Slack Channel",
      "description" : "This is a Slack channel",
      "config_type" : "slack",
      "is_enabled" : true
    },
    {
      "config_id" : "sample-id2",
      "name" : "Test chime channel",
      "description" : "A test chime channel",
      "config_type" : "chime",
      "is_enabled" : true
    }
  ]
}

List all notification configurations

To retrieve a list of notification configurations of all types, send a GET request to the configs resource.

Endpoints

GET /_plugins/_notifications/configs

Query parameters

The following table lists the available query parameters. All query parameters are optional. Unrecognized query parameters are rejected.

The following filter parameters match configurations whose field exactly equals the specified value. Where noted, specify multiple comma-separated values to match any of them.

The following filter parameters match configurations whose field contains the specified text.

Example request

GET /_plugins/_notifications/configs

The following request returns the first 10 Slack and Amazon Chime configurations, sorted by name:

GET /_plugins/_notifications/configs?config_type=slack,chime&sort_field=name&sort_order=asc&max_items=10

Example response

{
  "start_index" : 0,
  "total_hits" : 2,
  "total_hit_relation" : "eq",
  "config_list" : [
    {
      "config_id" : "sample-id",
      "last_updated_time_ms" : 1652760532774,
      "created_time_ms" : 1652760532774,
      "config" : {
        "name" : "Sample Slack Channel",
        "description" : "This is a Slack channel",
        "config_type" : "slack",
        "is_enabled" : true,
        "slack" : {
          "url" : "https://hooks.slack.com/services/<webhook-path>"
        }
      }
    },
    {
      "config_id" : "sample-id2",
      "last_updated_time_ms" : 1652760735380,
      "created_time_ms" : 1652760735380,
      "config" : {
        "name" : "Test chime channel",
        "description" : "A test chime channel",
        "config_type" : "chime",
        "is_enabled" : true,
        "chime" : {
          "url" : "https://hooks.chime.aws/incomingwebhooks/<webhook-id>?token=<token>"
        }
      }
    }
  ]
}

Response body fields

The following table lists all response body fields.

Each object in the config_list array contains the following fields.

Create channel configuration

To create a notification configuration, send a POST request to the configs resource. Use this request to create channels, email senders, and email recipient groups.

If you omit config_id, OpenSearch generates an ID. If you specify a config_id that already exists, the request fails with a 409 Conflict status. To modify an existing configuration, use the Update channel configuration API.

Endpoints

POST /_plugins/_notifications/configs

Request body fields

The following table lists the available request body fields.

The config object contains the following fields.

Slack, Amazon Chime, and Microsoft Teams

The slack, chime, and microsoft_teams objects contain the following field.

Custom webhook

The webhook object contains the following fields.

Email channel

The email object contains the following fields. The sender and recipient groups must exist before you create the channel.

Amazon SNS

The sns object contains the following fields.

SMTP sender

The smtp_account object contains the following fields.

Amazon SES sender

The ses_account object contains the following fields.

Email recipient group

The email_group object contains the following field.

Example: Creating a Slack channel

POST /_plugins/_notifications/configs
{
  "config_id": "sample-id",
  "config": {
    "name": "Sample Slack Channel",
    "description": "This is a Slack channel",
    "config_type": "slack",
    "is_enabled": true,
    "slack": {
      "url": "https://hooks.slack.com/services/<webhook-path>"
    }
  }
}

Example: Creating a custom webhook channel

POST /_plugins/_notifications/configs
{
  "config_id": "sample-webhook-id",
  "config": {
    "name": "Sample Webhook Channel",
    "config_type": "webhook",
    "webhook": {
      "url": "https://custom-webhook-test-url.com:8888/test-path?params1=value1&params2=value2",
      "header_params": {
        "Content-Type": "application/json"
      },
      "method": "POST"
    }
  }
}

Example: Creating an email channel

An email channel requires an email sender. The following request creates an SMTP sender:

POST /_plugins/_notifications/configs
{
  "config_id": "sample-smtp-id",
  "config": {
    "name": "sample-smtp-sender",
    "config_type": "smtp_account",
    "smtp_account": {
      "host": "smtp.example.com",
      "port": 587,
      "method": "start_tls",
      "from_address": "alerts@example.com"
    }
  }
}

The following request creates an email recipient group:

POST /_plugins/_notifications/configs
{
  "config_id": "sample-email-group-id",
  "config": {
    "name": "sample-email-group",
    "config_type": "email_group",
    "email_group": {
      "recipient_list": [
        {
          "recipient": "test-email1@test.com"
        },
        {
          "recipient": "test-email2@test.com"
        }
      ]
    }
  }
}

The following request creates an email channel that sends messages through the SMTP sender to one recipient and to the recipient group:

POST /_plugins/_notifications/configs
{
  "config_id": "sample-email-id",
  "config": {
    "name": "Sample Email Channel",
    "description": "Sample email description",
    "config_type": "email",
    "is_enabled": true,
    "email": {
      "email_account_id": "sample-smtp-id",
      "recipient_list": [
        {
          "recipient": "sample@email.com"
        }
      ],
      "email_group_id_list": ["sample-email-group-id"]
    }
  }
}

To use an Amazon SES sender, create an ses_account configuration and specify its ID in email_account_id. The following request creates an Amazon SES sender:

POST /_plugins/_notifications/configs
{
  "config_id": "sample-ses-id",
  "config": {
    "name": "sample-ses-sender",
    "config_type": "ses_account",
    "ses_account": {
      "region": "us-east-1",
      "role_arn": "arn:aws:iam::012345678912:role/NotificationsSESRole",
      "from_address": "test@email.com"
    }
  }
}

Example: Creating an Amazon SNS channel

POST /_plugins/_notifications/configs
{
  "config_id": "sample-sns-id",
  "config": {
    "name": "Sample SNS Channel",
    "config_type": "sns",
    "sns": {
      "topic_arn": "arn:aws:sns:us-east-1:012345678912:sample-topic",
      "role_arn": "arn:aws:iam::012345678912:role/NotificationsSNSRole"
    }
  }
}

Example response

The response contains the configuration ID:

{
  "config_id" : "sample-id"
}

Get channel configuration

To get a notification configuration by its ID, send a GET request and specify the config_id as a path parameter.

Endpoints

GET /_plugins/_notifications/configs/{config_id}

Path parameters

The following table lists the available path parameters.

Example request

GET /_plugins/_notifications/configs/sample-id

Example response

The response has the same format as the List all notification configurations response:

{
  "start_index" : 0,
  "total_hits" : 1,
  "total_hit_relation" : "eq",
  "config_list" : [
    {
      "config_id" : "sample-id",
      "last_updated_time_ms" : 1652760532774,
      "created_time_ms" : 1652760532774,
      "config" : {
        "name" : "Sample Slack Channel",
        "description" : "This is a Slack channel",
        "config_type" : "slack",
        "is_enabled" : true,
        "slack" : {
          "url" : "https://hooks.slack.com/services/<webhook-path>"
        }
      }
    }
  ]
}

Update channel configuration

To update an existing notification configuration, send a PUT request to the configs resource and specify the configuration’s config_id as a path parameter. The request body contains the config object, which has the same fields as in the create request. The update replaces the entire configuration, so specify all fields, including the ones you don’t change. Fields that you omit are reset to their default values.

You cannot change the config_type of an existing configuration. A request that specifies a different config_type fails with a 409 Conflict status. If the config_id does not exist, the request fails with a 404 Not Found status. To create a configuration, use the Create channel configuration API.

Endpoints

PUT /_plugins/_notifications/configs/{config_id}

Path parameters

The following table lists the available path parameters.

Example request

PUT /_plugins/_notifications/configs/sample-id
{
  "config": {
    "name": "Slack Channel",
    "description": "This is an updated channel configuration",
    "config_type": "slack",
    "is_enabled": true,
    "slack": {
      "url": "https://hooks.slack.com/services/<webhook-path>"
    }
  }
}

Example response

{
  "config_id" : "sample-id"
}

Delete channel configuration

To delete one or more notification configurations, send a DELETE request to the configs resource. Specify one ID as a path parameter or specify a comma-separated list of IDs in the config_id_list query parameter. If any of the specified configurations does not exist, the request fails and OpenSearch does not delete any of them.

OpenSearch does not check whether other configurations use the configuration you delete. For example, you can delete an email sender that an email channel uses.

Endpoints

DELETE /_plugins/_notifications/configs/{config_id}
DELETE /_plugins/_notifications/configs?config_id_list=<config_id1>,<config_id2>

Path parameters

The following table lists the available path parameters.

Query parameters

The following table lists the available query parameters.

Example request

DELETE /_plugins/_notifications/configs/sample-id

Example response

{
  "delete_response_list" : {
    "sample-id" : "OK"
  }
}

Example: Deleting multiple configurations

DELETE /_plugins/_notifications/configs?config_id_list=sample-id,sample-id2,sample-id3

Example response

{
  "delete_response_list" : {
    "sample-id" : "OK",
    "sample-id2" : "OK",
    "sample-id3" : "OK"
  }
}

Send test notification

To send a test message to a channel, send a POST request to the feature/test resource and specify the channel’s config_id as a path parameter. The channel must be enabled and must be of the slack, chime, microsoft_teams, webhook, email, or sns type. Email senders and email recipient groups cannot receive test messages.

The test message title is Test Message Title-<config_id>, and the message body is Test message content body for config id <config_id>.

If OpenSearch delivers the message, the request returns a 200 OK status. If delivery fails, for example, because the destination is unreachable or rejects the message, the request returns an error. The error contains the delivery status that the destination returned.

Endpoints

POST /_plugins/_notifications/feature/test/{config_id}

Path parameters

The following table lists the available path parameters.

Example request

POST /_plugins/_notifications/feature/test/sample-webhook-id

Example response

{
  "event_source" : {
    "title" : "Test Message Title-sample-webhook-id",
    "reference_id" : "sample-webhook-id",
    "severity" : "info",
    "tags" : [ ]
  },
  "status_list" : [
    {
      "config_id" : "sample-webhook-id",
      "config_type" : "webhook",
      "config_name" : "Sample Webhook Channel",
      "email_recipient_status" : [ ],
      "delivery_status" : {
        "status_code" : "200",
        "status_text" : "ok"
      }
    }
  ]
}

Response body fields

The following table lists all response body fields.

The event_source object contains the following fields.

Each object in the status_list array contains the following fields.

The delivery_status object contains the following fields.