Notifcations Methods

Notification methods consists of data-driven alerts, user notification preferences, and webhooks.

Using the notification methods of the Tableau Server REST API you can:

List, update, or delete the data-driven alerts of a site
Get the details of a specific data-driven alert
Add or delete the users of a specific data-driven alert
Create a new Webhook for a site.
Delete a Webhook.
Get a list of Webhooks for a specific site.
Get the notification preferences for a specified site, filtered by channel and notification type.
Update user notifications preferences to enabled or disabled on a specified site.

Add User to Data-Driven Alert

Adds a specified user to the recipients list for a data-driven alert.

URI

POST /api/api-version/sites/site-id/dataAlerts/data-alert-id/users

Parameter Values

api-version	The version of the API to use, such as `3.16`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the specified data-driven alert.
data-alert-id	The ID of the data-driven alert. You can obtain this ID by calling Query Data-Driven Alerts.

Request Body

<tsRequest>
  <user id="user-id"/>
</tsRequest>

Permissions

This method can only be called by server administrators and site administrators, and by users who are owners of the specified alert.

Response Code

200

Response Body

<tsResponse>
  <user id="user-id"
    name="user-name"
    siteRole="site-role"
    externalAuthUserId="external-user-id"/>
</tsResponse>

Version

Version 3.2 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status	`error` Code	Condition	Details
403	403004	Write forbidden	A user called this method who does not have the required permissions.
403	409028	Adding recipient to data-driven alert forbidden	The user is not authorized to add the recipient to the data-driven alert.
404	404000	Site not found	The site ID or URL namespace in the URI doesn't correspond to an existing site.
404	404002	Resource Not Found	The user ID specified in the request body is invalid.
404	409023	Resource Not Found	The data-driven alert ID specified in the URI is invalid.
405	405000	Invalid request method	Request type was not POST.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.16/sites/13020592-762f-4de4-a25e-f4beb005836e/dataAlerts/e5a4b73e-5cbb-412d-907e-f31cc31684f7/users" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-user-to-alert.xml

Content of add-user-to-alert.xml:

<tsRequest>
  <user id="8eda27d9-5ad2-42cd-a39a-61bc01a423af"/>
</tsRequest>

Example response:


<tsResponse>
  <user id="8eda27d9-5ad2-42cd-a39a-61bc01a423af"
        name="admin"
        siteRole="ServerAdministrator"
        externalAuthUserId=""/>
</tsresponse>

Create a Webhook

Creates a new webhook for a site.

URI

POST /api/3.6/sites/<site-id>/webhooks

Parameter Values

site-id

The ID of the site in which you want to create the webhook.  

Request Body

<tsRequest>
  <webhook
    name="webhook-name"
    isEnabled="webhook-enabled-flag"
    event="api-event-name">
      <webhook-source>
        <webhook-source-api-event-name />
      </webhook-source>
      <webhook-destination>
        <webhook-destination-http method="POST" url="url"/>
     </webhook-destination>
  </webhook>
</tsRequest>

Attribute Values

webhook-name	This is required. A name for the webhook.
api-event-name \| webhook-source-api-event-name	You must specify one of these attribute values. The name of the Tableau event that triggers your webhook. The event name must be one of the supported events listed in the Trigger Events table. The event and webhook-source use different name values for the same event.  Recommended: Use the event attribute of the webhook to specify the triggering API event for the webhook. The webhook-source element serves the same purpose but is being deprecated in future versions of Tableau webhooks. If both events and webhook-source are specified, their events specified must match. If either are specified, with the other being NULL, then the specified event becomes the webhook trigger, whether the element containing the event name is event or webhook-source.
url	Required. The destination URL for the webhook. The webhook destination URL must be https and have a valid certificate.
webhook-enabled-flag	(Optional) Boolean. If true (default), the newly created webhook is enabled. If false then the webhook will be disabled.

Permissions

This method can only be called by server and site administrators.

Response Code

200

Response Body

<tsResponse>
  <webhook
    id="webhook-id"
    name="webhook-name"
    isEnabled="true-or-false"
    statusChangeReason="status-change-reason"
    event="api-event-name">
      <webhook-source>
        <webhook-source-api-event-name />
      </webhook-source>
      <webhook-destination>
        <webhook-destination-http method="POST" url="url"/>
      </webhook-destination>
        <owner id="webhook_owner_luid" name="webhook_owner_name"/>
  </webhook>
</tsResponse>

Response Headers

Location: /api/3.16/sites/site-id/webhooks/<new-webhook-id>

Delete Data-Driven Alert

Deletes the specified data-driven alert from the specified site.

URI

DELETE /api/api-version/sites/site-id/dataAlerts/data-alert-id

Parameter Values

api-version	The version of the API to use, such as `3.16`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the specified data-driven alert.
data-alert-id	The ID of the data-driven alert. You can obtain this ID by calling Query Data-Driven Alerts.

Request Body

None

Permissions

This method can only be called by server and site administrators, and by users who are owners or recipients of the specified data-driven alert.

Response Code

204

Response Body

None

Version

Version 3.2 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status	`error` Code	Condition	Details
403	403004	Delete forbidden	A user called this method who does not have the required permissions
404	409023	Resource Not Found	The data-driven alert ID specified in the URI is invalid.
404	404000	Site not found	The site ID or URL namespace in the URI doesn't correspond to an existing site.
405	405000	Invalid request method	Request type was not DELETE.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.16/sites/13020592-762f-4de4-a25e-f4beb005836e/dataAlerts/e5a4b73e-5cbb-412d-907e-f31cc31684f7" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Delete User from Data-Driven Alert

Removes a specified user from the recipients list for a data-driven alert.

URI

DELETE /api/api-version/sites/site-id/dataAlerts/data-alert-id/users/user-id

Parameter Values

api-version	The version of the API to use, such as `3.16`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the specified data-driven alert.
data-alert-id	The ID of the data-driven alert. You can obtain this ID by calling Query Data-Driven Alerts.
user-id	The ID (not name) of the user to remove from the data-driven alert.

Request Body

None

Permissions

This method can only be called by server and site administrators, and by users who are owners of the specified data-driven alert.

Response Code

204

Response Body

None

Version

Version 3.2 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status	`error` Code	Condition	Details
403	403004	Delete forbidden	A user called this method who does not have the required permissions.
403	409029	Deleting recipient from data-driven alert forbidden	The user is not authorized to remove the recipient from the data-driven alert.
404	404000	Site not found	The site ID or URL namespace in the URI doesn't correspond to an existing site.
404	404002	Resource Not Found	The user ID specified in the request body is invalid.
404	409023	Resource Not Found	The data-driven alert ID specified in the URI is invalid.
405	405000	Invalid request method	Request type was not DELETE.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.16/sites/13020592-762f-4de4-a25e-f4beb005836e/dataAlerts/e5a4b73e-5cbb-412d-907e-f31cc31684f7/users/ff43cb47-f208-4d2f-9a22-0fbb6d29f7f1" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Delete a Webhook

Deletes the specified webhook.

URI

DELETE /api/3.6/sites/<site-id>/webhooks/<webhook-id>

Parameter Values

site-id	The ID of the site that contains the workbook to be deleted.
webhook-id	The ID of the webhook.

Request Body

None.

Permissions

This method can only be called by server and site administrators.

Response Code

204

Response Body

None.

Get User Notification Preferences

Returns the notification preferences for the specified site. You can filter by channel and notification type. For more information about notifications, see Manage Your Account Settings.

URI

GET /api/api-version/sites/site-id/settings/notifications

GET /api/api-version/sites/site-id/settings/notifications?filter=filter-expression

Parameter Values

api-version The version of the API to use, such as 3.16. For more information, see REST API and Resource Versions.

site-id The ID of the site that contains the users.

filter-expression

(Optional) An expression that lets you specify a subset of notification preferences to return. You can filter on the following fields and corresponding options:

channel: email, in_app, and slack
notificationType: comments, webhooks, prepflow, share, dataalerts,and extractrefresh

You can include multiple filter expressions. For more information, see Filtering and Sorting.

Request Body

None

Permissions

This method can only be called by a Server Administrator, a Site Administrator Creator, or a Site Administrator Explorer.

Response Code

200

Response Body

<tsResponse>
  <userNotificationsPreferences>
    <userNotificationsPreference channel="channel"
      notificationType="notification-type"
      enabled="true-or-false"
      disabledByOverride="true-or-false"/>
    <userNotificationsPreference channel="channel"
      notificationType="notification-type"
      enabled="true-or-false"
      disabledByOverride="true-or-false"/>
   <!-- ... additional notification preferences ... -->
  </userNotifcationsPreferences>
</tsResponse>

Version

Version 3.15 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status	`error` Code	Condition	Details
400	409109	Invalid request	Invalid notification type.
400	409100	Invalid request	Invalid channel.
403	403004	Invalid permissions	Invalid permission to update site user notification settings.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
405	405000	Invalid request method	The request type was not GET.

For more information, see Handling Errors.

Example

Example response:

<tsResponse>
  <userNotificationsPreferences>
    <userNotificationsPreference channel="email"
      notificationType="comments"
      enabled="true"
      disabledByOverride="false"/>
    <userNotificationsPreference channel="email"
      notificationType="webhooks"
      enabled="true"
      disabledByOverride="false"/>
    <userNotificationsPreference channel="email"
      notificationType="prepflow" enabled="true"
      disabledByOverride="false"/>
    <userNotificationsPreference channel="email"
      notificationType="share"
      enabled="true"
      disabledByOverride="false"/>
    <userNotificationsPreference channel="email"
      notificationType="dataalerts"
      enabled="true"
      disabledByOverride="true"/>
    <userNotificationsPreference channel="email"
      notificationType="extractrefresh"
      enabled="true"
      disabledByOverride="false"/>
    <userNotificationsPreference channel="in_app"
      notificationType="comments"
      enabled="true"
      disabledByOverride="false"/>
    <userNotificationsPreference channel="in_app"
      notificationType="prepflow"
      enabled="true"
      disabledByOverride="false"/>
    <userNotificationsPreference channel="in_app"
      notificationType="share"
      enabled="true"
      disabledByOverride="false"/>
    <userNotificationsPreference channel="in_app"
      notificationType="extractrefresh"
      enabled="true"
      disabledByOverride="false"/>
    <userNotificationsPreference channel="slack"
      notificationType="comments"
      enabled="true"
      disabledByOverride="false"/>
    <userNotificationsPreference channel="slack"
      notificationType="prepflow"
      enabled="true"
      disabledByOverride="false"/>
    <userNotificationsPreference channel="slack"
      notificationType="share"
      enabled="true"
      disabledByOverride="false"/>
     <userNotificationsPreference channel="slack"
      notificationType="dataalerts"
      enabled="true"
      disabledByOverride="false"/>
  </userNotificationsPreferences>
</tsResponse>

Get a Webhook

Returns information about the specified webhook.

URI

GET /api/3.6/sites/<site-id>/webhooks/<webhook-id>

Parameter Values

site-id	The ID of the site that contains the webhook.
webhook-id	The ID of the webhook.

Request Body

None

Permissions

This method can only be called by server administrators.

Response Code

200

Response Body

<tsResponse>
  <webhook
    id="webhook-id"
    name="webhook-name"
    isEnabled="true"
    statusChangeReason=""
    event="api-event-name">
      <webhook-source>
        <webhook-source-api-event-name />
      </webhook-source>
      <webhook-destination>
        <webhook-destination-http method="POST" url="url"/>
      </webhook-destination>
      <owner id="webhook_owner_luid" name="webhook_owner_name"/>
  </webhook>
</tsResponse>

List Webhooks

Returns a list of all the webhooks on the specified site.

URI

GET /api/3.6/sites/<site-id>/webhooks

Parameter Values

site-id

The ID of the site that contains the webhooks.   

Request Body

None

Permissions

This method can only be called by server and site administrators.

Response Code

200

Response Body

<tsResponse>
  <webhooks>
    <webhook
      id="webhook-id"
      name="webhook-name"
      isEnabled="true"
      statusChangeReason=""
      event="api-event-name">
        <webhook-source>
          <webhook-source-api-event-name />
        </webhook-source>
        <webhook-destination>
          <webhook-destination-http method="POST" url="url"/>
        </webhook-destination>
        <owner id="webhook_owner_luid" name="webhook_owner_name"/>
  </webhook>
  <!--  ... additional webhooks ...  -->
  </webhooks>
</tsResponse>

Query Data-Driven Alerts

Returns a list of data-driven alerts in use on the specified site.

URI

GET /api/api-version/sites/site-id/dataAlerts

URI

GET /api/api-version/sites/site-id/dataAlerts?pageSize=page-size&pageNumber=page-number

URI

GET /api/api-version/sites/site-id/dataAlerts?filter=viewId:eq:view-luid

Parameter Values

api-version	The version of the API to use, such as `3.16`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains data-driven alerts.

Request Body

None

Permissions

This method can only be called by server and site administrators, and by users who are owners or recipients for one or more alerts. Server administrators will see alerts for all sites on the server.

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="1" pageSize="100" totalAvailable="1"/>
  <dataAlerts>
    <dataAlert id="alert-id" subject="alert-subject" creatorId="creator-id" createdAt="created-date" updatedAt="updated-date" frequency="alert-frequency" public="is-public-flag">
      <owner id="owner-id" name="username"/>
      <view id="view-id" name="view-name">
        <workbook id="workbook-id" name="workbook-name"/>
        <project id="project-id" name="project-name"/>
      </view>
    </dataAlert>
  </dataAlerts>
</tsResponse>

The createdAt and updatedAt values are dates and times in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

Version 3.2 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status	`error` Code	Condition	Details
400	400006	Invalid page number	The page number parameter is not an integer, is less than one, or is greater than the final page number for the sites at the requested page size.
400	400007	Invalid page size	The page size parameter is not an integer, or is less than one.
403	403004	Read forbidden	A user queried this method who does not have the required permissions
403	403014	Page size limit exceeded	The specified page size is larger than the maximum page size.
404	404000	Site not found	The site ID or URL namespace in the URI doesn't correspond to an existing site.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.16/sites/13020592-762f-4de4-a25e-f4beb005836e/dataAlerts" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse>
  <dataAlerts>
    <dataAlert id="e5a4b73e-5cbb-412d-907e-f31cc31684f7" subject="Data alert - Shipping" creatorId="8eda27d9-5ad2-42cd-a39a-61bc01a423af" createdAt="2018-08-13T20:55:29Z" updatedAt="2018-08-21T00:05:34Z" frequency="daily" public="true">
      <owner id="8eda27d9-5ad2-42cd-a39a-61bc01a423af" name="admin"/>
      <view id="defbf126-5e8b-4c12-9c55-6e772c91bf62" name="Shipping">
        <workbook id="4c384398-085c-4236-91a0-4f92bee1c9ba" name="Superstore"/>
        <project id="291de556-9f2b-11e8-a25f-631b5eb7ad77" name="Default"/>
      </view>
    </dataAlert>
  </dataAlerts>
</tsResponse>

Query Data-Driven Alert Details

Returns details on a specified data-driven alert, including the recipients of the alert.

URI

GET /api/api-version/sites/site-id/dataAlerts/data-alert-id

Parameter Values

api-version	The version of the API to use, such as `3.16`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the specified data-driven alert.
data-alert-id	The ID of the data-driven alert. You can obtain this ID by calling Query Data-Driven Alerts.

Request Body

None

Permissions

This method can only be called by server and site administrators, and by users who are owners or recipients of the specified alert.

Response Code

200

Response Body

<tsResponse>
  <dataAlert id="alert-id" subject="alert-subject" creatorId="creator-id" createdAt="created-date" updatedAt="updated-date" frequency="alert-frequency" public="is-public-flag">
    <owner id="owner-id" name="username"/>
      <view id="view-id" name="view-name">
        <workbook id="workbook-id" name="workbook-name"/>
        <project id="project-id" name="project-name"/>
      </view>
      <recipients>
        <recipient id="recipient-id"/>
      </recipients>
  </dataAlert>
</tsResponse>

The createdAt and updatedAt values are dates and times in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

Version 3.2 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status	`error` Code	Condition	Details
403	403004	Read forbidden	A user queried this method who does not have the required permissions
404	409023	Resource Not Found	The data-driven alert ID specified in the URI is invalid.
404	404000	Site not found	The site ID or URL namespace in the URI doesn't correspond to an existing site.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.16/sites/13020592-762f-4de4-a25e-f4beb005836e/dataAlerts/e5a4b73e-5cbb-412d-907e-f31cc31684f7" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse>
  <dataAlert id="e5a4b73e-5cbb-412d-907e-f31cc31684f7" subject="Data alert - Shipping" creatorId="8eda27d9-5ad2-42cd-a39a-61bc01a423af" createdAt="2018-08-13T20:55:29Z" updatedAt="2018-08-21T00:05:34Z" frequency="daily" public="true">
    <owner id="8eda27d9-5ad2-42cd-a39a-61bc01a423af" name="admin"/>
    <view id="defbf126-5e8b-4c12-9c55-6e772c91bf62" name="Shipping">
      <workbook id="4c384398-085c-4236-91a0-4f92bee1c9ba" name="Superstore"/>
      <project id="291de556-9f2b-11e8-a25f-631b5eb7ad77" name="Default"/>
    </view>
    <recipients>
      <recipient id="4"/>
    </recipients>
  </dataAlert>
</tsResponse>

Test a Webhook

Tests the specified webhook. Sends an empty payload to the configured destination URL of the webhook and returns the response from the server. This is useful for testing, to ensure that things are being sent from Tableau and received back as expected.

URI

GET /api/3.6/sites/<site-id>/webhooks/<webhook-id>/test

Parameter Values

site-id	The ID of the site that contains the webhook.
webhook-id	The ID of the webhook.

Request Body

None.

Permissions

This method can only be called by server and site administrators.

Response Code

200

Response Body

<tsResponse>
  <webhookTestResult id="9f9bcaf8-8c4c-403c-b7e1-10dd85620f00" status="200">
    <body></body>
  </webhookTestResult>
</tsResponse>

Update Data-Driven Alert

Update one or more settings for the specified data-driven alert; including the alert subject, frequency, and owner.

URI

PUT /api/api-version/sites/site-id/dataAlerts/data-alert-id

Parameter Values

api-version	The version of the API to use, such as `3.16`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the data-driven alert.
data-alert-id	The ID of the data-driven alert. You can obtain this ID by calling Query Data-Driven Alerts.

Request Body

<tsRequest>
    <dataAlert subject="data-alert-subject"
        frequency="data-alert-frequency" public="is-public-flag">
            <owner id="data-alert-owner-id"/>
    </dataAlert>
 </tsRequest>

Attribute Values

data-alert-subject	(Optional) The string to set as the new subject of the alert.
data-alert-frequency	(Optional) The frequency of the data-driven alert: once, frequently, hourly, daily, or weekly.
data-alert-owner-id	(Optional) The ID of the user to assign as owner of the data-driven alert.
is-public-flag	(Optional) Determines the visibility of the data-driven alert. If the flag is true, users with access to the view containing the alert can see the alert and add themselves as recipients. If the flag is false, then the alert is only visible to the owner, site or server administrators, and specific users they add as recipients. (Optional) Determines the visibility of the data-driven alert. If the flag is true, users with access to the view containing the alert can see the alert and add themselves as recipients. If the flag is false, then the alert is only visible to the owner, site or server administrators, and specific users they add as recipients.

Permissions

This method can only be called by server and site administrators, and by users who are owners of the specified alert.

Response Code

200

Response Body

<tsResponse>
  <dataAlert id="data-alert-id" subject="data-alert-subject" creatorId="user-id"
    createdAt="created-date" updatedAt="updated-date" frequency="data-alert-frequency" public="is-public-flag">
    <owner id="user-id" name="user-name" />
    <view id="view-id" name="view-name" >
      <workbook id="workbook-id" name="workbook-name" />
      <project id="project-id" name="project-name" />
    </view>
  </dataAlert>
</tsResponse>

The createdAt and updatedAt attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

Version 3.2 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status	`error` Code	Condition	Details
403	403004	Write forbidden	A user called this method who does not have the required permissions.
403	409030	Updating data-driven alert forbidden	The user is not authorized to update the data-driven alert.
404	409023	Resource Not Found	The data-driven alert ID specified in the URI is invalid.
404	404000	Site not found	The site ID or URL namespace in the URI doesn't correspond to an existing site.
404	404002	Resource Not Found	The user ID specified in the request body is invalid.
405	405000	Invalid request method	Request type was not PUT.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.16/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/dataAlerts/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @update-alert.xml

Content of update-alert.xml:

<tsRequest>
    <dataAlert subject="Data alert - Shipping" frequency="daily" public="true">
        <owner id="8eda27d9-5ad2-42cd-a39a-61bc01a423af"/>
    </dataAlert>
</tsRequest>

Example response:

<tsResponse>
  <dataAlert id="c60bbd4e-dd98-469f-bf71-83c42378f427" subject="Data alert - Shipping"
    creatorId="8eda27d9-5ad2-42cd-a39a-61bc01a423af" createdAt="2018-08-22T23:16:41Z"
    updatedAt="2018-08-24T20:27:14Z" frequency="daily" public="true">
    <owner id="8eda27d9-5ad2-42cd-a39a-61bc01a423af" name="admin"/>
    <view id="defbf126-5e8b-4c12-9c55-6e772c91bf62" name="Shipping">
      <workbook id="4c384398-085c-4236-91a0-4f92bee1c9ba" name="Superstore"/>
      <project id="291de556-9f2b-11e8-a25f-631b5eb7ad77" name="Default"/>
    </view>
  </dataAlert>
</tsResponse>

Update User Notification Preferences

Updates user notifications preferences to enabled or disabled on the specified site. For more information about notifications, see Manage Your Account Settings.

URI

PATCH /api/api_version/sites/site-id/settings/notifications

Parameter Values

api-version	The version of the API to use, such as `3.16`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the user.

Request Body

<tsRequest>
  <userNotificationsPreferences>
    <userNotificationsPreference
      enabled="enabled-flag"
      channel="channel"
      notificationType="notification-type"/>
    <userNotificationsPreference
      enabled="enabled-flag"
      channel="channel"
      notificationType="notification-type"/>
  <userNotificationsPreferences>
</tsRequest>

Attribute Values

enabled-flag	(Required, boolean) If `true`, the specified site notifications will be on. If `false`, the specified site notifications will be off.
channel	(Required, string) Specifies the channel that the notification preferences are to be updated (turned on or off). Valid channels are: email, in_app, and slack.
notification-type	Specifies the notification type for which the notification preferences are to be updated (turned on or off). Valid notification types are: comments, webhooks, prepflow, share, dataalerts,and extractrefresh.

Permissions

This method can only be called by a Server Administrator, a Site Administrator Creator, or a Site Administrator Explorer.

Response Code

200: The request was successful
207: One or more of the updates in the request resulted in an error. See details in the the response body.

Response Body

<tsResponse>
  <notificationUpdateResult>
    <notificationUpdateStatus>
      <status>Success</status>
        <userNotificationsPreference channel="channel"
          notificationType="notification-type"
          enabled="enabled-flag"/>
        </notificationUpdateStatus>
    <notificationUpdateStatus>
      <status>Success</status>
        <userNotificationsPreference channel="channel"
          notificationType="notification-type"
          enabled="enabled-flag"/>
    </notificationUpdateStatus>
  </notificationUpdateResult>
</tsResponse>

Version

Version 3.15 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status	`error` Code	Condition	Details
403	403004	Invalid Permissions	Invalid permission to update site user notification settings.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
405	405000	Invalid request method	The request type was not PATCH.

For more information, see Handling Errors.

Example response

<tsResponse>
  <notificationUpdateResult>
    <notificationUpdateStatus>
      <status>Success</status>
        <userNotificationsPreference channel="slack"
          notificationType="comments"
          enabled="false"/>
      </notificationUpdateStatus>
      <notificationUpdateStatus>
        <status>Success</status>
        <userNotificationsPreference channel="email"
          notificationType="comments"
          enabled="false"/>
      </notificationUpdateStatus>
  </notificationUpdateResult>
</tsResponse>

Update a Webhook

Modify the properties of an existing webhook.

URI

PUT /api/3.8/sites/<site-id>/webhooks/<webhook-id>

Parameter Values

site-id	The ID of the site that contains the webhook to be updated.
webhook-id	The ID of the webhook.

Request Body

<tsRequest>
  <webhook name="webhook-name"
    isEnabled="webhook-enabled-flag"
    statusChangeReason="reason-for-disablement"
    event="api-event-name">
      <webhook-source>
        <webhook-source-api-event-name />
      </webhook-source>
      <webhook-destination>
        <webhook-destination-http method="POST" url="url" />
      </webhook-destination>
  </webhook>
</tsRequest>

Attribute Values

webhook-name	This is required. A name for the webhook.
api-event-name \| webhook-source-api-event-name	You must specify one of these attribute values. The name of the Tableau event that triggers your webhook. The event name must be one of the supported events listed in the Trigger Events table. The event and webhook-source use different name values for the same event.  Recommended: Use the event attribute of the webhook to specify the triggering API event for the webhook. The webhook-source element serves the same purpose but is being deprecated in future versions of Tableau webhooks. If both events and webhook-source are specified, their events specified must match. If either are specified, with the other being NULL, then the specified event becomes the webhook trigger, whether the element containing the event name is event or webhook-source.
url	(Optional) The destination URL for the webhook. The webhook destination URL must be https and have a valid certificate.
webhook-enabled-flag	(Optional) Boolean. If true (default), the newly created webhook is enabled. If false then the webhook will be disabled.
reason-for-disablement	The reason a webhook is disabled. If isEnabled set to true, omit this parameter from your request to create a webhook, or set the value of statusChangeReason to an empty string. Providing a reason value when creating an enabled webhook will result in an error (400127). If isEnabled set to false, then unless you provide a value for statusChangeReason it will default to "Webhook disabled by user".

Permissions

This method can only be called by server and site administrators.

Response Code

201 Success.

Response Body

<tsResponse>
  <webhook
    id="webhook-id"
    name="webhook-name"
    isEnabled="true"
    statusChangeReason=""
    event="api-event-name">
      <webhook-source>
        <webhook-source-api-event-name />
      </webhook-source>
      <webhook-destination>
        <webhook-destination-http method="POST" url="url"/>
      </webhook-destination>
      <owner id="webhook_owner_luid" name="webhook_owner_name"/>
  </webhook>
</tsResponse>

Errors

HTTP status	`error` Code	Condition	Details
400	400127	Bad request	statusChangeReason was provided with isEnabled = true

For more information, see Handling Errors.

Response Headers

Location: /api/3.16/sites/site-id/webhooks/new-webhook-id

Thanks for your feedback!

Tableau REST API Help

Add User to Data-Driven Alert

URI

Parameter Values

Request Body

Permissions

Response Code

Response Body

Version

Errors

Example

Create a Webhook

URI

Parameter Values

Request Body

Attribute Values

Permissions

Response Code

Response Body

Response Headers

Delete Data-Driven Alert

URI

Parameter Values

Request Body

Permissions

Response Code

Response Body

Version

Errors

Example

Delete User from Data-Driven Alert

URI

Parameter Values

Request Body

Permissions

Response Code

Response Body

Version

Errors

Example

Delete a Webhook

URI

Parameter Values

Request Body

Permissions

Response Code

Response Body

Get User Notification Preferences

URI

Parameter Values

Request Body

Permissions

Response Code

Response Body

Version

Errors

Example

Get a Webhook

URI

Parameter Values

Request Body

Permissions

Response Code

Response Body

List Webhooks

URI

Parameter Values

Request Body

Permissions

Response Code

Response Body

Query Data-Driven Alerts

URI

URI

URI

Parameter Values

Request Body

Permissions

Response Code

Response Body