Notifications API

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

Sample Request

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. }

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

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"
  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:

Sample Response

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

Get channel configuration

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.       "config" : {
  10.         "name" : "Sample Slack Channel",
  11.         "description" : "This is a Slack channel",
  13.         "is_enabled" : true,
  14.         "slack" : {
  15.           "url" : "https://sample-slack-webhook"
  16.         }
  17.       }
  18.     }
  19.   ]
  20. }

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

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. }

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.     }