Configuring notifications in Management API¶

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.

Note

Notification subscriptions are owned by the user who created them. As a Notifications Administrator, you can only modify or delete the email, Slack, and Microsoft Teams subscriptions that you own. To change a subscription owned by another user, ask that user or a root workspace Administrator to make the change.

This ownership rule does not apply to webhook subscriptions. Any Notifications Administrator can modify or delete any webhook subscription.

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

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:

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:

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:

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:

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.