Configuring notifications in Management API

This article explains how to create, configure, and delete email, Slack, and Microsoft Teams notifications with the Management API.

Prerequisites

• To configure notifications, the user performing these actions must have the Notifications Administrator role assigned in the Adverity user interface. For more information, see Changing user permissions in Adverity.

• Create and configure a workspace in Adverity. In the following documents, you can find how to list specific workspaces.

  • For more information on creating workspaces, see Creating workspaces in Management API.

    For more information on configuring workspaces, see Configuring workspaces in Management API.

• Create and configure a datastream. For more information, see Creating datastreams.

• For Slack or Microsoft Teams notifications, obtain a webhook. For more information, see Prerequisites in Managing user notifications.

Configuring and creating email notifications

Listing current email notifications

To list currently configured email notifications, follow these steps:

1. Create a GET request to the following endpoint:

   https://{{INSTANCE}}/api/notifications/email/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request GET 'https://{{INSTANCE}}/api/notifications/email/' \
--header 'Authorization: Token {{KEY}}'

Retrieving specific email notification details

To retrieve a specific email notification configuration, follow these steps:

1. Create a GET request to the following endpoint:

   https://{{INSTANCE}}/api/notifications/email/{{EMAIL_NOTIFICATION_ID}}/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request GET 'https://{{INSTANCE}}/api/notifications/email/{{EMAIL_NOTIFICATION_ID}}/' \
--header 'Authorization: Token {{KEY}}'

Creating a new email notification

To create a new email notification, follow these steps:

1. Create a POST request to the following endpoint:

   https://{{INSTANCE}}/api/notifications/email/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. In the HTTP request header, include the parameter Content-Type with value application/json.

4. In the HTTP request body, include the following parameters in JSON. Change the placeholder values as necessary:

   {
       "topics": [
           "ABC"
       ],
       "stacks": [
           "STACK_ID"
       ],
       "email": "RECIPIENT@DOMAIN.com"
   }
   

5. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request POST 'https://{{INSTANCE}}/api/notifications/email/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "topics": [
        "ABC"
    ],
    "stacks": [
        "STACK_ID"
    ],
    "email": "RECIPIENT@DOMAIN.com"
}'

Note

If you provide an email address that is not associated with your workspace, you receive the error message Email provided is not associated with any existing user.

Available topics for email notifications

The API names of the topics are different compared to UI names. The table below displays available topics for email notifications compared to their UI name:

UI topic name	API topic name
Authentication	oauth
Daily import status	import_status
Datastream and transformation Issues	datastream
Import errors	import
Mapping	mapping
Data Mapping	schema_mapping
Smart Naming Convention	smart_naming_convention
Workspace mapping	workspace_mapping

Modifying an email notification

To modify an email notification, follow these steps:

1. Create a PATCH request to the following endpoint:

   https://{{INSTANCE}}/api/notifications/email/{{EMAIL_NOTIFICATION_ID}}/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. In the HTTP request header, include the parameter Content-Type with value application/json.

4. In the HTTP request body, include the parameters and values to modify in JSON. For example, to change the email parameter, use the following:

   {
       "email": "NEW_RECIPIENT@DOMAIN.COM"
   }
   

5. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request PATCH 'https://{{INSTANCE}}/api/notifications/email/{{EMAIL_NOTIFICATION_ID}}/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{"email": "NEW_RECIPIENT@DOMAIN.COM"}'

Deleting an email notification

To delete an email notification, follow these steps:

1. Create a DELETE request to the following endpoint:

   https://{{INSTANCE}}/api/notifications/email/{{EMAIL_NOTIFICATION_ID}}/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request DELETE 'https://{{INSTANCE}}/api/notifications/email/{{EMAIL_NOTIFICATION_ID}}/' \
--header 'Authorization: Token {{KEY}}'

Creating and configuring Slack notifications

Listing current Slack notifications

To list currently configured Slack notifications, follow these steps:

1. Create a GET request to the following endpoint:

   https://{{INSTANCE}}/api/notifications/slack/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request GET 'https://{{INSTANCE}}/api/notifications/slack/' \
--header 'Authorization: Token {{KEY}}'

Retrieving a specific Slack notification details

To retrieve a specific Slack notification configuration, follow these steps:

1. Create a GET request to the following endpoint:

   https://{{INSTANCE}}/api/notifications/slack/{{SLACK_NOTIFICATION_ID}}/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request GET 'https://{{INSTANCE}}/api/notifications/slack/{{SLACK_NOTIFICATION_ID}}/' \
--header 'Authorization: Token {{KEY}}'

Creating a new Slack notification

To create a new Slack notification, follow these steps:

1. Create a POST request to the following endpoint:

   https://{{INSTANCE}}/api/notifications/slack/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. In the HTTP request header, include the parameter Content-Type with value application/json.

4. In the HTTP request body, include the following parameters in JSON. Change the placeholder values as necessary:

   {
       "webhook_url": "https://hooks.slack.com/services/VALID_WEBHOOK_ID",
       "topics": [
           "ABC",
           "XYZ"
       ]
   }
   

5. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request POST 'https://{{INSTANCE}}/api/notifications/slack/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "webhook_url": "https://hooks.slack.com/services/VALID_WEBHOOK_ID",
    "topics": [
        "ABC",
        "XYZ"
    ]
}'

Available topics for Slack notifications

The API names of the topics are different compared to UI names. The table below displays available topics for Slack notifications compared to their UI name:

UI topic name	API topic name
Authentication	oauth
Datastream and transformation Issues	datastream
Import Errors	import
Mapping	mapping
Data Mapping	schema_mapping
Smart Naming Convention	smart_naming_convention
Workspace Mapping	workspace_mapping

Modifying Slack notification

To modify Slack notification, follow these steps:

1. Create a PATCH request to the following endpoint:

   https://{{INSTANCE}}/api/notifications/slack/{{SLACK_NOTIFICATION_ID}}/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. In the HTTP request header, include the parameter Content-Type with value application/json.

4. In the HTTP request body, include the parameters and values to modify in JSON. For example, to change the datastreams parameter, use the following:

   {
       "datastreams": [DATASTREAM_ID]
   }
   

5. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request PATCH 'https://{{INSTANCE}}/api/notifications/slack/{{SLACK_NOTIFICATION_ID}}/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "datastreams": [DATASTREAM_ID]
}'

Deleting Slack notification

To delete a Slack notification, follow these steps:

1. Create a DELETE request to the following endpoint:

   https://{{INSTANCE}}/api/notifications/slack/{{SLACK_NOTIFICATION_ID}}/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request DELETE 'https://{{INSTANCE}}/api/notifications/slack/{{SLACK_NOTIFICATION_ID}}/' \
--header 'Authorization: Token {{KEY}}'

Configuring and creating Microsoft Teams notifications

Listing current Microsoft Teams notifications

To list currently configured Microsoft Teams notifications, follow these steps:

1. Create a GET request to the following endpoint:

   https://{{INSTANCE}}/api/notifications/microsoftteams/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request GET 'https://{{INSTANCE}}/api/notifications/email/' \
--header 'Authorization: Token {{KEY}}'

Retrieving specific Microsoft Teams notification details

To retrieve a specific Microsoft Teams notification configuration, follow these steps:

1. Create a GET request to the following endpoint:

   https://{{INSTANCE}}/api/notifications/microsoftteams/{{MICROSOFT_TEAMS_NOTIFICATION_ID}}/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request GET 'https://{{INSTANCE}}/api/notifications/microsoftteams/{{MICROSOFT_TEAMS_NOTIFICATION_ID}}/' \
--header 'Authorization: Token {{KEY}}'

Creating new Microsoft Teams notification

To create a new Microsoft Teams notification, follow these steps:

1. Create a POST request to the following endpoint:

   https://{{INSTANCE}}/api/notifications/microsoftteams/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. In the HTTP request header, include the parameter Content-Type with value application/json.

4. In the HTTP request body, include the following parameters in JSON. Change the placeholder values as necessary:

   {
       "webhook_url": "https://WEBHOOK_URL/VALID_WEBHOOK_ID",
       "topics": [
           "ABC",
           "XYZ"
       ]
   }
   

5. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request POST 'https://{{INSTANCE}}/api/notifications/microsoftteams/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "webhook_url": "https://WEBHOOK_URL/VALID_WEBHOOK_ID",
    "topics": [
        "ABC",
        "XYZ"
    ]
}'

Available topics for Microsoft Teams notifications

The API names of the topics are different compared to UI names. The table below displays available topics for Microsoft Teams notifications compared to their UI name:

UI topic name	API topic name
Authentication	oauth
Datastream and transformation Issues	datastream
Import Errors	import
Mapping	mapping
Data Mapping	schema_mapping
Smart Naming Convention	smart_naming_convention
Workspace Mapping	workspace_mapping

Modifying Microsoft Teams notification

To modify a Microsoft Teams notification, follow these steps:

1. Create a PATCH request to the following endpoint:

   https://{{INSTANCE}}/api/notifications/microsoftteams/{{MICROSOFT_TEAMS_NOTIFICATION_ID}}/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. In the HTTP request header, include the parameter Content-Type with value application/json.

4. In the HTTP request body, include the parameters and values to modify in JSON. For example, to change the datastreams parameter, use the following:

   {
       "datastreams": [DATASTREAM_ID]
   }
   

5. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request PATCH 'https://{{INSTANCE}}/api/notifications/microsoftteams/{{MICROSOFT_TEAMS_NOTIFICATION_ID}}/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "datastreams": [DATASTREAM_ID]
}'

Deleting Microsoft Teams notification

To delete a Microsoft Teams notification, follow these steps:

1. Create a DELETE request to the following endpoint:

   https://{{INSTANCE}}/api/notifications/microsoftteams/{{MICROSOFT_TEAMS_NOTIFICATION_ID}}/
   

2. In the HTTP request header, include the parameter Authorization with one of the following values:

   • Token {{KEY}} if you use a key generated with user credentials in Management API.

   • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

3. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request DELETE 'https://{{INSTANCE}}/api/notifications/microsoftteams/{{MICROSOFT_TEAMS_NOTIFICATION_ID}}/' \
--header 'Authorization: Token {{KEY}}'

Explanations for parameters

topics

Criteria that trigger a notification. Required parameter.

stacks

The workspace on which the notification is triggered. If you do not specify this parameter, all workspaces where you are a Notifications Administrator are used. Use the stack_id.

enabled

Boolean value. If the notification is active, the default value is true.

datastreams

The individual datastreams where a particular notification is applied. The value is datastream_id. If you do not specify this parameter, notification runs in all datastreams in the selected workspaces.