Configuring notifications in Management API

On this page

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

See POST /api/notifications/email/, POST /api/notifications/slack/, POST /api/notifications/webhook/ and POST /api/notifications/microsoftteams/ in the API reference.

Prerequisites

Use a Connect API key with the following permissions:
- User: Read-only (user:read) to list and view notification subscriptions.
- User: Write (user:write) to create, update, or delete notification subscriptions.
You can select the User permission only on a key for the root workspace, and only if you are an Administrator. Picking Write for a permission also gives the key its Read-only access. Subscriptions that you create with a key are owned by the user the key belongs to. Without the permission a request needs, Management API returns HTTP 403. You cannot change the permissions of a key, so to add one, create a new key. For more information, see Creating a Connect API key in Adverity.
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:

Create a GET request to the following endpoint:

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

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
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: Bearer {{KEY}}'

Retrieving specific email notification details

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

Create a GET request to the following endpoint:

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

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
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: Bearer {{KEY}}'

Creating a new email notification

To create a new email notification, follow these steps:

Create a POST request to the following endpoint:
```
https://{{INSTANCE}}/api/notifications/email/
```
In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
In the HTTP request header, include the parameter Content-Type with value application/json.

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

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: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "topics": [
        "ABC"
    ],
    "stacks": [
        "STACK_ID"
    ],
    "email": "RECIPIENT@DOMAIN.com"
}'

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:

Scroll horizontally to see the full table.

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:

Create a PATCH request to the following endpoint:

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

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
In the HTTP request header, include the parameter Content-Type with value application/json.
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"
}
```
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: Bearer {{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:

Create a DELETE request to the following endpoint:

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

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
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: Bearer {{KEY}}'

Creating and configuring Slack notifications

Listing current Slack notifications

To list currently configured Slack notifications, follow these steps:

Create a GET request to the following endpoint:

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

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
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: Bearer {{KEY}}'

Retrieving a specific Slack notification details

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

Create a GET request to the following endpoint:

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

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
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: Bearer {{KEY}}'

Creating a new Slack notification

To create a new Slack notification, follow these steps:

Create a POST request to the following endpoint:
```
https://{{INSTANCE}}/api/notifications/slack/
```
In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
In the HTTP request header, include the parameter Content-Type with value application/json.

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"
    ]
}

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: Bearer {{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:

Scroll horizontally to see the full table.

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:

Create a PATCH request to the following endpoint:

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

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
In the HTTP request header, include the parameter Content-Type with value application/json.
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]
}
```
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: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "datastreams": [DATASTREAM_ID]
}'

Deleting Slack notification

To delete a Slack notification, follow these steps:

Create a DELETE request to the following endpoint:

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

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
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: Bearer {{KEY}}'

Configuring and creating Microsoft Teams notifications

Listing current Microsoft Teams notifications

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

Create a GET request to the following endpoint:

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

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
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/' \
--header 'Authorization: Bearer {{KEY}}'

Retrieving specific Microsoft Teams notification details

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

Create a GET request to the following endpoint:

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

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
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: Bearer {{KEY}}'

Creating new Microsoft Teams notification

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

Create a POST request to the following endpoint:

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

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
In the HTTP request header, include the parameter Content-Type with value application/json.

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"
    ]
}

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: Bearer {{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:

Scroll horizontally to see the full table.

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:

Create a PATCH request to the following endpoint:

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

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
In the HTTP request header, include the parameter Content-Type with value application/json.
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]
}
```
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: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "datastreams": [DATASTREAM_ID]
}'

Deleting Microsoft Teams notification

To delete a Microsoft Teams notification, follow these steps:

Create a DELETE request to the following endpoint:

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

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
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: Bearer {{KEY}}'

Configuring and creating webhook notifications

Webhook notifications send a payload to a URL you specify when a subscribed event occurs, so you can integrate Adverity events with your own systems. Unlike email, Slack, and Microsoft Teams notifications, webhook notifications subscribe to events rather than topics and are not scoped to specific workspaces or datastreams.

Listing current webhook notifications

To list currently configured webhook notifications, follow these steps:

Create a GET request to the following endpoint:

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

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
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/webhook/' \
--header 'Authorization: Bearer {{KEY}}'

Retrieving specific webhook notification details

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

Create a GET request to the following endpoint:

https://{{INSTANCE}}/api/notifications/webhook/{{WEBHOOK_NOTIFICATION_ID}}/

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
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/webhook/{{WEBHOOK_NOTIFICATION_ID}}/' \
--header 'Authorization: Bearer {{KEY}}'

Creating a new webhook notification

To create a new webhook notification, follow these steps:

Create a POST request to the following endpoint:

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

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
In the HTTP request header, include the parameter Content-Type with value application/json.

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

{
    "payload_url": "https://YOUR_ENDPOINT/webhook",
    "events": [
        "issue.created"
    ],
    "enabled": true,
    "secret": "YOUR_SIGNING_SECRET"
}

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/webhook/' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "payload_url": "https://YOUR_ENDPOINT/webhook",
    "events": [
        "issue.created"
    ],
    "enabled": true,
    "secret": "YOUR_SIGNING_SECRET"
}'

Available events for webhook notifications

The following events are available for webhook notifications:

Scroll horizontally to see the full table.

Event	Triggered when
`destination_sync.end`	A destination sync finishes.
`extract.no_data_collected`	A fetch completes without collecting any data.
`issue.created`	A new error is created.
`integrations.dbt.DbtJobRun.end`	A dbt transformation job run finishes.

Modifying a webhook notification

To modify a webhook notification, follow these steps:

Create a PATCH request to the following endpoint:

https://{{INSTANCE}}/api/notifications/webhook/{{WEBHOOK_NOTIFICATION_ID}}/

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
In the HTTP request header, include the parameter Content-Type with value application/json.
In the HTTP request body, include the parameters and values to modify in JSON. For example, to disable the webhook, use the following:
```
{
    "enabled": false
}
```
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/webhook/{{WEBHOOK_NOTIFICATION_ID}}/' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "enabled": false
}'

Deleting a webhook notification

To delete a webhook notification, follow these steps:

Create a DELETE request to the following endpoint:

https://{{INSTANCE}}/api/notifications/webhook/{{WEBHOOK_NOTIFICATION_ID}}/

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
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/webhook/{{WEBHOOK_NOTIFICATION_ID}}/' \
--header 'Authorization: Bearer {{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.
notify_about_empty_extracts: Boolean value. Available for email, Slack, and Microsoft Teams notifications. If true, Adverity also sends the notification when a datastream fetches a data extract without any data. This only applies if the datastream topic is included in topics.
exclude_warnings: Boolean value. Available for email, Slack, and Microsoft Teams notifications. If true, Adverity only sends the notification for errors, not warnings.
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.
email: The email address of the recipient of the email notification.
webhook_url: The webhook URL for Slack or Microsoft Teams notifications.
payload_url: The URL that Adverity sends the payload to for a webhook notification.
events: The events that trigger a webhook notification. Required for webhook notifications. For the available values, see Available events for webhook notifications.
secret: Optional signing secret for a webhook notification. It is write-only and is not returned in responses.