Notifications API

If you want to programmatically define your notification channels and sources for versioning and reuse, you can use the Notifications REST API to define, configure, and delete notification channels and send test messages.

List supported channel configurations

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

Sample Request

  1. GET /_plugins/_notifications/features

Sample Response

  1. {
  2.   "allowed_config_type_list" : [
  3.     "slack",
  4.     "chime",
  5.     "webhook",
  6.     "email",
  7.     "sns",
  8.     "ses_account",
  9.     "smtp_account",
  10.     "email_group"
  11.   ],
  12.   "plugin_features" : {
  13.     "tooltip_support" : "true"
  14.   }
  15. }

List all notification configurations

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

Sample Request

  1. GET _plugins/_notifications/configs

Sample Response

  1. {
  2.   "start_index" : 0,
  3.   "total_hits" : 2,
  4.   "total_hit_relation" : "eq",
  5.   "config_list" : [
  6.     {
  7.       "config_id" : "sample-id",
  8.       "last_updated_time_ms" : 1652760532774,
  9.       "created_time_ms" : 1652760532774,
  10.       "config" : {
  11.         "name" : "Sample Slack Channel",
  12.         "description" : "This is a Slack channel",
  13.         "config_type" : "slack",
  14.         "is_enabled" : true,
  15.         "slack" : {
  16.           "url" : "https://sample-slack-webhook"
  17.         }
  18.       }
  19.     },
  20.     {
  21.       "config_id" : "sample-id2",
  22.       "last_updated_time_ms" : 1652760735380,
  23.       "created_time_ms" : 1652760735380,
  24.       "config" : {
  25.         "name" : "Test chime channel",
  26.         "description" : "A test chime channel",
  27.         "config_type" : "chime",
  28.         "is_enabled" : true,
  29.         "chime" : {
  30.           "url" : "https://sample-chime-webhook"
  31.         }
  32.       }
  33.     }
  34.   ]
  35. }

To filter the notification configuration types this request returns, you can refine your query with the following optional path parameters.

ParameterDescription
config_idSpecifies the channel identifier.
config_id_listSpecifies a comma-separated list of channel IDs.
from_indexThe starting index to search from.
max_itemsThe maximum amount of items to return in your request.
sort_orderSpecifies the direction to sort results in. Valid options are asc and desc.
sort_fieldField to sort results with.
last_updated_time_msThe Unix time in milliseconds of when the channel was last updated.
created_time_msThe Unix time in milliseconds of when the channel was created.
is_enabledIndicates whether the channel is enabled.
config_typeThe channel type. Valid options are sns, slack, chime, webhook, smtp_account, ses_account, email_group, and email.
nameThe channel’s name.
descriptionThe channel’s description.
email.email_account_idThe sender email addresses the channel uses.
email.email_group_id_listThe email groups the channel uses.
email.recipient_listThe channel’s recipient list.
email_group.recipient_listThe channel’s list of email recipient groups.
smtp_account.methodThe email encryption method.
slack.urlThe Slack channel’s URL.
chime.urlThe Amazon Chime connection’s URL.
webhook.urlThe webhook’s URL.
smtp_account.hostThe domain of the SMTP account.
smtp_account.from_addressThe email account’s sender address.
smtp_account.methodThe SMTP account’s encryption method.
sns.topic_arnThe Amazon Simple Notification Service (SNS) topic’s ARN.
sns.role_arnThe Amazon SNS topic’s role ARN.
ses_account.regionThe Amazon Simple Email Service (SES) account’s AWS Region.
ses_account.role_arnThe Amazon SES account’s role ARN.
ses_account.from_addressThe Amazon SES account’s sender email address.

Create channel configuration

To create a notification channel configuration, send a POST request to the configs resource.

Sample Request

  1. POST /_plugins/_notifications/configs/
  2. {
  3.   "config_id": "sample-id",
  4.   "name": "sample-name",
  5.   "config": {
  6.     "name": "Sample Slack Channel",
  7.     "description": "This is a Slack channel",
  8.     "config_type": "slack",
  9.     "is_enabled": true,
  10.     "slack": {
  11.       "url": "https://sample-slack-webhook"
  12.     }
  13.   }
  14. }

The create channel API operation accepts the following fields in its request body:

FieldData typeDescriptionRequired
config_idStringThe configuration’s custom ID.No
configObjectContains all relevant information, such as channel name, configuration type, and plugin source.Yes
nameStringName of the channel.Yes
descriptionStringThe channel’s description.No
config_typeStringThe destination of your notification. Valid options are sns, slack, chime, webhook, smtp_account, ses_account, email_group, and email.Yes
is_enabledBooleanIndicates whether the channel is enabled for sending and receiving notifications. Default is true.No

The create channel operation accepts multiple config_types as possible notification destinations, so follow the format for your preferred config_type.

  1. "sns": {
  2.   "topic_arn": "<arn>",
  3.   "role_arn": "<arn>" //optional
  4. }
  5. "slack": {
  6.   "url": "https://sample-chime-webhoook"
  7. }
  8. "chime": {
  9.   "url": "https://sample-amazon-chime-webhoook"
  10. }
  11. "webhook": {
  12.       "url": "https://custom-webhook-test-url.com:8888/test-path?params1=value1&params2=value2"
  13. }
  14. "smtp_account": {
  15.   "host": "test-host.com",
  16.   "port": 123,
  17.   "method": "start_tls",
  18.   "from_address": "test@email.com"
  19. }
  20. "ses_account": {
  21.   "region": "us-east-1",
  22.   "role_arn": "arn:aws:iam::012345678912:role/NotificationsSESRole",
  23.   "from_address": "test@email.com"
  24. }
  25. "email_group": { //Email recipient group
  26.   "recipient_list": [
  27.     {
  28.       "recipient": "test-email1@test.com"
  29.     },
  30.     {
  31.       "recipient": "test-email2@test.com"
  32.     }
  33.   ]
  34. }
  35. "email": { //The channel that sends emails
  36.   "email_account_id": "<smtp or ses account config id>",
  37.   "recipient_list": [
  38.     {
  39.       "recipient": "custom.email@test.com"
  40.     }
  41.   ],
  42.   "email_group_id_list": []
  43. }

The following example demonstrates how to create a channel using email as a config_type:

  1. POST /_plugins/_notifications/configs/
  2. {
  3.   "id": "sample-email-id",
  4.   "name": "sample-name",
  5.   "config": {
  6.     "name": "Sample Email Channel",
  7.     "description": "Sample email description",
  8.     "config_type": "email",
  9.     "is_enabled": true,
  10.     "email": {
  11.       "email_account_id": "<email_account_id>",
  12.       "recipient_list": [
  13.         "sample@email.com"
  14.       ]
  15.     }
  16.   }
  17. }

Sample Response

  1. {
  2.   "config_id" : "<config_id>"
  3. }

Get channel configuration

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

Sample Request

  1. GET _plugins/_notifications/configs/<config_id>

Sample Response

  1. {
  2.   "start_index" : 0,
  3.   "total_hits" : 1,
  4.   "total_hit_relation" : "eq",
  5.   "config_list" : [
  6.     {
  7.       "config_id" : "sample-id",
  8.       "last_updated_time_ms" : 1652760532774,
  9.       "created_time_ms" : 1652760532774,
  10.       "config" : {
  11.         "name" : "Sample Slack Channel",
  12.         "description" : "This is a Slack channel",
  13.         "config_type" : "slack",
  14.         "is_enabled" : true,
  15.         "slack" : {
  16.           "url" : "https://sample-slack-webhook"
  17.         }
  18.       }
  19.     }
  20.   ]
  21. }

Update channel configuration

To update a channel configuration, send a POST request to the configs resource and specify the channel’s config_id as a path parameter. Specify the new configuration details in the request body.

Sample Request

  1. PUT _plugins/_notifications/configs/<config_id>
  2. {
  3.   "config": {
  4.     "name": "Slack Channel",
  5.     "description": "This is an updated channel configuration",
  6.     "config_type": "slack",
  7.     "is_enabled": true,
  8.     "slack": {
  9.       "url": "https://hooks.slack.com/sample-url"
  10.     }
  11.   }
  12. }

Sample Response

  1. {
  2.   "config_id" : "<config_id>"
  3. }

Delete channel configuration

To delete a channel configuration, send a DELETE request to the configs resource and specify the config_id as a path parameter.

Sample Request

  1. DELETE /_plugins/_notifications/configs/<config_id>

Sample Response

  1. {
  2.   "delete_response_list" : {
  3.   "<config_id>" : "OK"
  4.   }
  5. }

You can also submit a comma-separated list of channel IDs you want to delete, and OpenSearch deletes all of the specified notification channels.

Sample Request

  1. DELETE /_plugins/_notifications/configs/?config_id_list=<config_id1>,<config_id2>,<config_id3>...

Sample Response

  1. {
  2.   "delete_response_list" : {
  3.   "<config_id1>" : "OK",
  4.   "<config_id2>" : "OK",
  5.   "<config_id3>" : "OK"
  6.   }
  7. }

Send test notification

To send a test notification, send a GET request to /feature/test/ and specify the channel configuration’s config_id as a path parameter.

Sample Request

  1. GET _plugins/_notifications/feature/test/<config_id>

Sample Response

  1. {
  2.   "event_source" : {
  3.     "title" : "Test Message Title-0Jnlh4ABa4TCWn5C5H2G",
  4.     "reference_id" : "0Jnlh4ABa4TCWn5C5H2G",
  5.     "severity" : "info",
  6.     "tags" : [ ]
  7.   },
  8.   "status_list" : [
  9.     {
  10.       "config_id" : "0Jnlh4ABa4TCWn5C5H2G",
  11.       "config_type" : "slack",
  12.       "config_name" : "sample-id",
  13.       "email_recipient_status" : [ ],
  14.       "delivery_status" : {
  15.         "status_code" : "200",
  16.         "status_text" : """<!doctype html>
  17. <html>
  18. <head>
  19. </head>
  20. <body>
  21. <div>
  22.     <h1>Example Domain</h1>
  23.     <p>Sample paragraph.</p>
  24.     <p><a href="sample.example.com">TO BE OR NOT TO BE, THAT IS THE QUESTION</a></p>
  25. </div>
  26. </body>
  27. </html>
  28. """
  29.       }
  30.     }
  31.   ]
  32. }