Skip to main content

Notification Destination

View as Markdown

A reusable definition of where a workspace sends notifications, such as a Slack channel, a set of email addresses, a PagerDuty service, a Microsoft Teams channel or a generic webhook. Job notifications, SQL alerts and other workspace features reference a destination by its id. Only workspace admins can create, update and delete destinations; once created, a destination is available to all users in the workspace. Secret values such as webhook URLs and tokens are write-only: responses report whether each one is set, never its value.

NotificationDestination object​

A reusable definition of where a workspace sends notifications, such as a Slack channel, a set of email addresses, a PagerDuty service, a Microsoft Teams channel or a generic webhook. Job notifications, SQL alerts and other workspace features reference a destination by its id. Only workspace admins can create, update and delete destinations; once created, a destination is available to all users in the workspace. Secret values such as webhook URLs and tokens are write-only: responses report whether each one is set, never its value.

idstring

A UUID identifying the notification destination.

Example: fe25e731-92f2-4838-9fb2-1ca364320a3d

display_namestring

The display name for the notification destination.

Example: My slack destination

destination_typestring

[Output-only] The type of the notification destination, determined by which nested config was provided on creation. The type can not be changed once set.

Values:

  • SLACK
  • EMAIL
  • WEBHOOK
  • PAGERDUTY
  • MICROSOFT_TEAMS
  • DATABRICKS_APP_SLACK Beta
  • DATABRICKS_APP_TEAMS Beta
configobject

The configuration for the notification destination. Will be exactly one of the nested configs. Only returned to users with workspace admin permissions.

Show child attributesHide child attributes
slackobject

Configures a Slack incoming webhook destination.

Show child attributesHide child attributes
urlstring

[Input-Only] Slack incoming webhook URL that notifications are posted to. Must be an HTTPS URL. The URL is required even when oauth_token and channel_id are set.

Example: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXX

url_setboolean

[Output-Only] Whether URL is set.

oauth_tokenstring

[Input-Only] Slack bot OAuth token (xoxb-...). Optional; when set together with channel_id, notifications are posted to that channel through the Slack API.

oauth_token_setboolean

[Output-Only] Whether OAuth token is set.

channel_idstring

[Input-Only] ID of the Slack channel that notifications are posted to through the Slack API. Optional; set it together with oauth_token.

Example: C1234567890

channel_id_setboolean

[Output-Only] Whether channel ID is set.

emailobject

Configures an email destination.

Show child attributesHide child attributes
addressesarray of string

Email addresses to notify. At least one address is required.

generic_webhookobject

Configures a generic HTTPS webhook destination.

Show child attributesHide child attributes
urlstring

[Input-Only] HTTPS URL that notifications are posted to.

Example: https://my-webhook.com

url_setboolean

[Output-Only] Whether URL is set.

usernamestring

[Input-Only][Optional] Username for HTTP Basic authentication. Set it together with password.

Example: username

username_setboolean

[Output-Only] Whether username is set.

passwordstring

[Input-Only][Optional] Password for HTTP Basic authentication. Set it together with username.

Example: password

password_setboolean

[Output-Only] Whether password is set.

pagerdutyobject

Configures a PagerDuty destination.

Show child attributesHide child attributes
integration_keystring

[Input-Only] Integration key from an Events API v2 integration on the PagerDuty service that receives the notifications.

Example: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

integration_key_setboolean

[Output-Only] Whether integration key is set.

microsoft_teamsobject

Configures a Microsoft Teams incoming webhook destination.

Show child attributesHide child attributes
urlstring

[Input-Only] Microsoft Teams incoming webhook URL that notifications are posted to. Must be an HTTPS URL. The URL is required even when the app fields are set.

Example: https://outlook.office.com/webhook/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

url_setboolean

[Output-Only] Whether URL is set.

app_idstring

[Input-Only] Application (client) ID of the Microsoft Teams app, as a UUID. Optional; set it together with auth_secret, channel_url and tenant_id.

Example: 00000000-0000-0000-0000-000000000000

app_id_setboolean

[Output-Only] Whether App ID is set.

auth_secretstring

[Input-Only] Client secret of the Microsoft Teams app. Optional; set it together with app_id, channel_url and tenant_id.

Example: 0p8S~exampleSecretValue12345

auth_secret_setboolean

[Output-Only] Whether secret is set.

channel_urlstring

[Input-Only] URL of the Microsoft Teams channel that the app posts to. Optional; set it together with app_id, auth_secret and tenant_id.

channel_url_setboolean

[Output-Only] Whether Channel URL is set.

tenant_idstring

[Input-Only] Microsoft Entra tenant ID of the Microsoft Teams app, as a UUID. Optional; set it together with app_id, auth_secret and channel_url.

Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

tenant_id_setboolean

[Output-Only] Whether Tenant ID is set.

databricks_app_slackobjectBeta

Configures a Slack channel reached through the Databricks Genie app for Slack.

Show child attributesHide child attributes
team_idstringBeta

[Input-Only] Slack workspace (team) ID the Databricks app is installed in.

Example: T1234567890

team_id_setbooleanBeta

[Output-Only] Whether team ID is set.

channel_idstringBeta

[Input-Only] Slack channel ID notifications are posted to.

Example: C1234567890

channel_id_setbooleanBeta

[Output-Only] Whether channel ID is set.

databricks_app_teamsobjectBeta

Configures a Microsoft Teams channel reached through the Databricks Genie app for Microsoft Teams.

Show child attributesHide child attributes
tenant_idstringBeta

[Input-Only] Microsoft Entra tenant ID of the Microsoft 365 tenant the app is installed in.

Example: 00000000-0000-0000-0000-000000000000

tenant_id_setbooleanBeta

[Output-Only] Whether tenant ID is set.

team_idstringBeta

[Input-Only] Microsoft Entra group ID of the team that owns the channel.

Example: 00000000-0000-0000-0000-000000000001

team_id_setbooleanBeta

[Output-Only] Whether team ID is set.

channel_idstringBeta

[Input-Only] Teams channel ID notifications are posted to.

Example: 19:abc123@thread.tacv2

channel_id_setbooleanBeta

[Output-Only] Whether channel ID is set.

Get a notification destination GA​

GET /api/2.0/notification-destinations/{id}

Gets a notification destination by ID. Workspace admins also receive its config.

API scopes: notifications

Parameters​

idstringRequiredpath

A UUID identifying the notification destination.

Example: fe25e731-92f2-4838-9fb2-1ca364320a3d

Response​

Returns the NotificationDestination object.

List notification destinations GA​

GET /api/2.0/notification-destinations

Lists the notification destinations in the workspace. Results never include a destination's config; workspace admins can retrieve it with Get.

API scopes: notifications

Parameters​

page_tokenstringquery

Opaque token returned as next_page_token by a previous call. Omit it to request the first page.

page_sizeint64query

Maximum number of notification destinations to return per page. Defaults to 20.

Default: 20

Response​

resultsarray of object

Notification destinations in the current page.

Show child attributesHide child attributes
idstring

A UUID identifying the notification destination.

Example: fe25e731-92f2-4838-9fb2-1ca364320a3d

display_namestring

The display name for the notification destination.

Example: My slack destination

destination_typestring

[Output-only] The type of the notification destination, determined by which nested config was provided on creation. The type can not be changed once set.

Values:

  • SLACK
  • EMAIL
  • WEBHOOK
  • PAGERDUTY
  • MICROSOFT_TEAMS
  • DATABRICKS_APP_SLACK Beta
  • DATABRICKS_APP_TEAMS Beta
configobject

The configuration for the notification destination. Will be exactly one of the nested configs. Only returned to users with workspace admin permissions.

Show child attributesHide child attributes
slackobject

Configures a Slack incoming webhook destination.

Show child attributesHide child attributes
urlstring

[Input-Only] Slack incoming webhook URL that notifications are posted to. Must be an HTTPS URL. The URL is required even when oauth_token and channel_id are set.

Example: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXX

url_setboolean

[Output-Only] Whether URL is set.

oauth_tokenstring

[Input-Only] Slack bot OAuth token (xoxb-...). Optional; when set together with channel_id, notifications are posted to that channel through the Slack API.

oauth_token_setboolean

[Output-Only] Whether OAuth token is set.

channel_idstring

[Input-Only] ID of the Slack channel that notifications are posted to through the Slack API. Optional; set it together with oauth_token.

Example: C1234567890

channel_id_setboolean

[Output-Only] Whether channel ID is set.

emailobject

Configures an email destination.

Show child attributesHide child attributes
addressesarray of string

Email addresses to notify. At least one address is required.

generic_webhookobject

Configures a generic HTTPS webhook destination.

Show child attributesHide child attributes
urlstring

[Input-Only] HTTPS URL that notifications are posted to.

Example: https://my-webhook.com

url_setboolean

[Output-Only] Whether URL is set.

usernamestring

[Input-Only][Optional] Username for HTTP Basic authentication. Set it together with password.

Example: username

username_setboolean

[Output-Only] Whether username is set.

passwordstring

[Input-Only][Optional] Password for HTTP Basic authentication. Set it together with username.

Example: password

password_setboolean

[Output-Only] Whether password is set.

pagerdutyobject

Configures a PagerDuty destination.

Show child attributesHide child attributes
integration_keystring

[Input-Only] Integration key from an Events API v2 integration on the PagerDuty service that receives the notifications.

Example: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

integration_key_setboolean

[Output-Only] Whether integration key is set.

microsoft_teamsobject

Configures a Microsoft Teams incoming webhook destination.

Show child attributesHide child attributes
urlstring

[Input-Only] Microsoft Teams incoming webhook URL that notifications are posted to. Must be an HTTPS URL. The URL is required even when the app fields are set.

Example: https://outlook.office.com/webhook/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

url_setboolean

[Output-Only] Whether URL is set.

app_idstring

[Input-Only] Application (client) ID of the Microsoft Teams app, as a UUID. Optional; set it together with auth_secret, channel_url and tenant_id.

Example: 00000000-0000-0000-0000-000000000000

app_id_setboolean

[Output-Only] Whether App ID is set.

auth_secretstring

[Input-Only] Client secret of the Microsoft Teams app. Optional; set it together with app_id, channel_url and tenant_id.

Example: 0p8S~exampleSecretValue12345

auth_secret_setboolean

[Output-Only] Whether secret is set.

channel_urlstring

[Input-Only] URL of the Microsoft Teams channel that the app posts to. Optional; set it together with app_id, auth_secret and tenant_id.

channel_url_setboolean

[Output-Only] Whether Channel URL is set.

tenant_idstring

[Input-Only] Microsoft Entra tenant ID of the Microsoft Teams app, as a UUID. Optional; set it together with app_id, auth_secret and channel_url.

Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

tenant_id_setboolean

[Output-Only] Whether Tenant ID is set.

databricks_app_slackobjectBeta

Configures a Slack channel reached through the Databricks Genie app for Slack.

Show child attributesHide child attributes
team_idstringBeta

[Input-Only] Slack workspace (team) ID the Databricks app is installed in.

Example: T1234567890

team_id_setbooleanBeta

[Output-Only] Whether team ID is set.

channel_idstringBeta

[Input-Only] Slack channel ID notifications are posted to.

Example: C1234567890

channel_id_setbooleanBeta

[Output-Only] Whether channel ID is set.

databricks_app_teamsobjectBeta

Configures a Microsoft Teams channel reached through the Databricks Genie app for Microsoft Teams.

Show child attributesHide child attributes
tenant_idstringBeta

[Input-Only] Microsoft Entra tenant ID of the Microsoft 365 tenant the app is installed in.

Example: 00000000-0000-0000-0000-000000000000

tenant_id_setbooleanBeta

[Output-Only] Whether tenant ID is set.

team_idstringBeta

[Input-Only] Microsoft Entra group ID of the team that owns the channel.

Example: 00000000-0000-0000-0000-000000000001

team_id_setbooleanBeta

[Output-Only] Whether team ID is set.

channel_idstringBeta

[Input-Only] Teams channel ID notifications are posted to.

Example: 19:abc123@thread.tacv2

channel_id_setbooleanBeta

[Output-Only] Whether channel ID is set.

next_page_tokenstring

Token to pass as page_token to fetch the next page of results. Absent when there are no more results.

Create a notification destination GA​

POST /api/2.0/notification-destinations

Creates a notification destination. Requires workspace admin permissions.

API scopes: notifications

Request body​

display_namestring

The display name for the notification destination.

configobject

The configuration for the notification destination. Must wrap EXACTLY one of the nested configs.

Show child attributesHide child attributes
slackobject

Configures a Slack incoming webhook destination.

Show child attributesHide child attributes
urlstring

[Input-Only] Slack incoming webhook URL that notifications are posted to. Must be an HTTPS URL. The URL is required even when oauth_token and channel_id are set.

Example: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXX

url_setboolean

[Output-Only] Whether URL is set.

oauth_tokenstring

[Input-Only] Slack bot OAuth token (xoxb-...). Optional; when set together with channel_id, notifications are posted to that channel through the Slack API.

oauth_token_setboolean

[Output-Only] Whether OAuth token is set.

channel_idstring

[Input-Only] ID of the Slack channel that notifications are posted to through the Slack API. Optional; set it together with oauth_token.

Example: C1234567890

channel_id_setboolean

[Output-Only] Whether channel ID is set.

emailobject

Configures an email destination.

Show child attributesHide child attributes
addressesarray of string

Email addresses to notify. At least one address is required.

generic_webhookobject

Configures a generic HTTPS webhook destination.

Show child attributesHide child attributes
urlstring

[Input-Only] HTTPS URL that notifications are posted to.

Example: https://my-webhook.com

url_setboolean

[Output-Only] Whether URL is set.

usernamestring

[Input-Only][Optional] Username for HTTP Basic authentication. Set it together with password.

Example: username

username_setboolean

[Output-Only] Whether username is set.

passwordstring

[Input-Only][Optional] Password for HTTP Basic authentication. Set it together with username.

Example: password

password_setboolean

[Output-Only] Whether password is set.

pagerdutyobject

Configures a PagerDuty destination.

Show child attributesHide child attributes
integration_keystring

[Input-Only] Integration key from an Events API v2 integration on the PagerDuty service that receives the notifications.

Example: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

integration_key_setboolean

[Output-Only] Whether integration key is set.

microsoft_teamsobject

Configures a Microsoft Teams incoming webhook destination.

Show child attributesHide child attributes
urlstring

[Input-Only] Microsoft Teams incoming webhook URL that notifications are posted to. Must be an HTTPS URL. The URL is required even when the app fields are set.

Example: https://outlook.office.com/webhook/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

url_setboolean

[Output-Only] Whether URL is set.

app_idstring

[Input-Only] Application (client) ID of the Microsoft Teams app, as a UUID. Optional; set it together with auth_secret, channel_url and tenant_id.

Example: 00000000-0000-0000-0000-000000000000

app_id_setboolean

[Output-Only] Whether App ID is set.

auth_secretstring

[Input-Only] Client secret of the Microsoft Teams app. Optional; set it together with app_id, channel_url and tenant_id.

Example: 0p8S~exampleSecretValue12345

auth_secret_setboolean

[Output-Only] Whether secret is set.

channel_urlstring

[Input-Only] URL of the Microsoft Teams channel that the app posts to. Optional; set it together with app_id, auth_secret and tenant_id.

channel_url_setboolean

[Output-Only] Whether Channel URL is set.

tenant_idstring

[Input-Only] Microsoft Entra tenant ID of the Microsoft Teams app, as a UUID. Optional; set it together with app_id, auth_secret and channel_url.

Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

tenant_id_setboolean

[Output-Only] Whether Tenant ID is set.

databricks_app_slackobjectBeta

Configures a Slack channel reached through the Databricks Genie app for Slack.

Show child attributesHide child attributes
team_idstringBeta

[Input-Only] Slack workspace (team) ID the Databricks app is installed in.

Example: T1234567890

team_id_setbooleanBeta

[Output-Only] Whether team ID is set.

channel_idstringBeta

[Input-Only] Slack channel ID notifications are posted to.

Example: C1234567890

channel_id_setbooleanBeta

[Output-Only] Whether channel ID is set.

databricks_app_teamsobjectBeta

Configures a Microsoft Teams channel reached through the Databricks Genie app for Microsoft Teams.

Show child attributesHide child attributes
tenant_idstringBeta

[Input-Only] Microsoft Entra tenant ID of the Microsoft 365 tenant the app is installed in.

Example: 00000000-0000-0000-0000-000000000000

tenant_id_setbooleanBeta

[Output-Only] Whether tenant ID is set.

team_idstringBeta

[Input-Only] Microsoft Entra group ID of the team that owns the channel.

Example: 00000000-0000-0000-0000-000000000001

team_id_setbooleanBeta

[Output-Only] Whether team ID is set.

channel_idstringBeta

[Input-Only] Teams channel ID notifications are posted to.

Example: 19:abc123@thread.tacv2

channel_id_setbooleanBeta

[Output-Only] Whether channel ID is set.

Response​

Returns the NotificationDestination object.

Update a notification destination GA​

PATCH /api/2.0/notification-destinations/{id}

Updates a notification destination. Requires workspace admin permissions. At least one field is required in the request body. A config provided in the request replaces the existing one.

API scopes: notifications

Parameters​

idstringRequiredpath

A UUID identifying the notification destination.

Example: fe25e731-92f2-4838-9fb2-1ca364320a3d

Request body​

display_namestring

The display name for the notification destination.

configobject

The configuration for the notification destination. Must wrap EXACTLY one of the nested configs.

Show child attributesHide child attributes
slackobject

Configures a Slack incoming webhook destination.

Show child attributesHide child attributes
urlstring

[Input-Only] Slack incoming webhook URL that notifications are posted to. Must be an HTTPS URL. The URL is required even when oauth_token and channel_id are set.

Example: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXX

url_setboolean

[Output-Only] Whether URL is set.

oauth_tokenstring

[Input-Only] Slack bot OAuth token (xoxb-...). Optional; when set together with channel_id, notifications are posted to that channel through the Slack API.

oauth_token_setboolean

[Output-Only] Whether OAuth token is set.

channel_idstring

[Input-Only] ID of the Slack channel that notifications are posted to through the Slack API. Optional; set it together with oauth_token.

Example: C1234567890

channel_id_setboolean

[Output-Only] Whether channel ID is set.

emailobject

Configures an email destination.

Show child attributesHide child attributes
addressesarray of string

Email addresses to notify. At least one address is required.

generic_webhookobject

Configures a generic HTTPS webhook destination.

Show child attributesHide child attributes
urlstring

[Input-Only] HTTPS URL that notifications are posted to.

Example: https://my-webhook.com

url_setboolean

[Output-Only] Whether URL is set.

usernamestring

[Input-Only][Optional] Username for HTTP Basic authentication. Set it together with password.

Example: username

username_setboolean

[Output-Only] Whether username is set.

passwordstring

[Input-Only][Optional] Password for HTTP Basic authentication. Set it together with username.

Example: password

password_setboolean

[Output-Only] Whether password is set.

pagerdutyobject

Configures a PagerDuty destination.

Show child attributesHide child attributes
integration_keystring

[Input-Only] Integration key from an Events API v2 integration on the PagerDuty service that receives the notifications.

Example: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

integration_key_setboolean

[Output-Only] Whether integration key is set.

microsoft_teamsobject

Configures a Microsoft Teams incoming webhook destination.

Show child attributesHide child attributes
urlstring

[Input-Only] Microsoft Teams incoming webhook URL that notifications are posted to. Must be an HTTPS URL. The URL is required even when the app fields are set.

Example: https://outlook.office.com/webhook/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

url_setboolean

[Output-Only] Whether URL is set.

app_idstring

[Input-Only] Application (client) ID of the Microsoft Teams app, as a UUID. Optional; set it together with auth_secret, channel_url and tenant_id.

Example: 00000000-0000-0000-0000-000000000000

app_id_setboolean

[Output-Only] Whether App ID is set.

auth_secretstring

[Input-Only] Client secret of the Microsoft Teams app. Optional; set it together with app_id, channel_url and tenant_id.

Example: 0p8S~exampleSecretValue12345

auth_secret_setboolean

[Output-Only] Whether secret is set.

channel_urlstring

[Input-Only] URL of the Microsoft Teams channel that the app posts to. Optional; set it together with app_id, auth_secret and tenant_id.

channel_url_setboolean

[Output-Only] Whether Channel URL is set.

tenant_idstring

[Input-Only] Microsoft Entra tenant ID of the Microsoft Teams app, as a UUID. Optional; set it together with app_id, auth_secret and channel_url.

Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

tenant_id_setboolean

[Output-Only] Whether Tenant ID is set.

databricks_app_slackobjectBeta

Configures a Slack channel reached through the Databricks Genie app for Slack.

Show child attributesHide child attributes
team_idstringBeta

[Input-Only] Slack workspace (team) ID the Databricks app is installed in.

Example: T1234567890

team_id_setbooleanBeta

[Output-Only] Whether team ID is set.

channel_idstringBeta

[Input-Only] Slack channel ID notifications are posted to.

Example: C1234567890

channel_id_setbooleanBeta

[Output-Only] Whether channel ID is set.

databricks_app_teamsobjectBeta

Configures a Microsoft Teams channel reached through the Databricks Genie app for Microsoft Teams.

Show child attributesHide child attributes
tenant_idstringBeta

[Input-Only] Microsoft Entra tenant ID of the Microsoft 365 tenant the app is installed in.

Example: 00000000-0000-0000-0000-000000000000

tenant_id_setbooleanBeta

[Output-Only] Whether tenant ID is set.

team_idstringBeta

[Input-Only] Microsoft Entra group ID of the team that owns the channel.

Example: 00000000-0000-0000-0000-000000000001

team_id_setbooleanBeta

[Output-Only] Whether team ID is set.

channel_idstringBeta

[Input-Only] Teams channel ID notifications are posted to.

Example: 19:abc123@thread.tacv2

channel_id_setbooleanBeta

[Output-Only] Whether channel ID is set.

Response​

Returns the NotificationDestination object.

Delete a notification destination GA​

DELETE /api/2.0/notification-destinations/{id}

Deletes a notification destination. Requires workspace admin permissions.

API scopes: notifications

Parameters​

idstringRequiredpath

A UUID identifying the notification destination.

Example: fe25e731-92f2-4838-9fb2-1ca364320a3d