# tableau Tableau Webhooks (developer) - Full Documentation # About Tableau Help ## Addressing Implicit Bias in Technical Language In an effort to align with one of our core company values, equality, we have changed terminology to be more inclusive where possible. Because changing terms in certain places can causing a breaking change, we maintain existing terminology in the following places: - Tableau APIs: methods, parameters, and variables - Tableau CLIs: commands and options - Installers, installation directories, and terms in configuration files - Tableau Resource Monitoring Tool (we plan to make changes to non-inclusive terminology in the web interface, error messages, and related documentation soon.) - Third-party systems documentation For more information about our ongoing effort to address implicit bias, see [Salesforce Updates Technical Language in Ongoing Effort to Address Implicit Bias](https://www.salesforce.com/news/stories/salesforce-updates-technical-language-in-ongoing-effort-to-address-implicit-bias/) on the Salesforce website. # Get Started with Tableau Webhooks In this topic: ## Overview Webhooks let you build custom applications or workflows that react to events that happen in Tableau. For example, you could use webhooks to send an SMS or Slack notification any time a datasource refresh fails, or fire off a confetti cannon when a new workbook is created.  For the initial release, webhooks are supported for a selected set of [datasource and workbook events](/v0.0/developer/webhooks/en-us/docs/webhooks-events-payload.html).   You configure each webhook to subscribe to an event in Tableau. Then, when the event occurs, an HTTP POST request will be sent to the public URL you specified. This POST request includes a JSON payload that includes information about the event. The payload includes the ID of the object in question so that the Tableau REST API can be used to get additional information or take further action.  ## Prerequisites   To use Tableau webhooks, you must be authenticated as a site administrator for the Tableau Cloud or Server instance where the webhooks feature is enabled, for example, [https://10ax.online.tableau.com](https://10ax.online.tableau.com/).  You can set up your own Tableau Cloud instance and get many other benefits at no cost by joining the [Tableau Developer Program](https://developer.tableau.com). ## Set Up a Webhook Using Postman Here is an example of setting up a webhook with the REST API using Postman. 1. Download the following files (follow the link and save from your browser or IDE: [https://github.com/tableau/rest-api-samples/tree/master/postman](https://github.com/tableau/rest-api-samples/tree/master/postman) 2. Download and install Postman from [https://www.getpostman.com/](https://www.getpostman.com/). 3. Launch Postman and click **File** > **Import**  and choose the Postman collection and environment files you downloaded and then select **Import**. 4. Choose the **Tableau Webhooks Requests** collection on the left, and then select **Tableau Webhooks** from the environment dropdown menu on the top right. 5. To configure environment variables for webhooks, click the sliders icon near the environment dropdown. In the **MANAGE ENVIRONMENTS** dialog, select **Tableau Webhooks**. Replace the placeholder URL for the `server` variable in the **CURRENT VARIABLE** column with your server URL (like `https://10ax.online.tableau.com`). Fill in the `content-url` environment variable for your site (content-url value would be `my_site` if your site url looks like this - `https://10ax.online.tableau.com/site/my_site/projects`). Add either your username and password or your Personal Access Token name and secret. Click **Update** and close the dialog. 6. In the **Tableau Webhooks Requests** collection, choose the **Sign-in** request. You can choose either the username/password method or the personal access token method. Click **Send**. The response body contains the site id and a token. 7. Open the **MANAGE ENVIRONMENTS** dialog from the sliders icon, open **Tableau Webhooks** variables, and use the site id and token to set **CURRENT VALUE** of the `site_id` and `tableau_auth_token` variables. 8. In the list of requests, click **Create a webhook**. In the request body, enter a webhook `name`, a Tableau trigger event name from the [Trigger Events](/v0.0/developer/webhooks/en-us/docs/webhooks-events-payload.html) table, and a destination `url`. The destination URL must be https and have a valid certificate. 9. Click **Send**, and then use the ID of your new webhook from the response body to set the `webhook-id` environment variable in the **MANAGE ENVIRONMENTS** dialog. 10. In the list of requests, choose **Test a webhook** and click **Send**. Testing the 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 webhooks POSTs are being sent from Tableau and a response is returned from the destination as expected. ## Set Up a Webhook Using cURL Here is an example of setting up a webhook with the REST API using cURL. ### Sign In `curl "http:///api/3.1/auth/signin" -X POST -d @signin.xml` Content of signin.xml: ```         ``` ### Create a Webhook `curl "http:///api/3.6/sites//webhooks" -X POST -H "X-Tableau-Auth:" -d @details.xml` Replace token with the token from the sign in response body. Content of details.xml: ```                   ``` Replace URL with the destination URL for the webhook. The webhook destination URL must be https and have a valid certificate. ### Test the Webhook Testing the 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. `curl "http:///api/3.6/sites//webhooks//test" -X GET -H "X-Tableau-Auth:"` Replace `webhook-id` with the webhook id from the create webhook response body. See the [Test a Webhook](#testawebhook) endpoint for more information. ### List Webhooks `curl "http:///api/3.6/sites//webhooks" -X GET -H "X-Tableau-Auth:"` ## Webhooks Tutorials ### Set up a Tableau Webhook Using Glitch and If This Then That In this tutorial, you can learn how to set up a [Glitch](http://glitch.com) project with [If This Then That](https://ifttt.com/) (IFTTT) as the service that processes your webhook message. - [Send a message when a workbook is created](https://github.com/tableau/datadev-hackathon/wiki/Send-a-notification-when-a-workbook-is-created) ### Integrate Tableau Webhooks with Slack Using Glitch In this tutorial, you can learn how to use a [Glitch](http://glitch.com) project to integrate your webhook message into [Slack](https://slack.com). Using these techniques can help you avoid commonly seen HTTP 400 errors. - [Send a Slack notification when a workbook is created](https://github.com/tableau/datadev-hackathon/wiki/Send-a-Slack-notification-when-a-workbook-is-updated) # Tableau Webhooks Webhooks are a common method whereby one computer system can notify another that an event has occurred using standard web technologies such as HTTP and JSON. With Tableau Webhooks, you have the ability to automatically trigger these workflows. When events happen in Tableau, a notification can be sent wherever you want, triggering a workflow. Here are some examples of what you can do with Webhooks: - When an extract refresh fails, file a ticket in ServiceNow automatically. - When a workbook is updated, notify your team via their Slack channel. - When a data source is published, email a data steward asking them to review and certify it. - When a workbook refresh completes successfully, generate a PDF and post it to SharePoint. System and Site Admins have the ability to create and manage Webhooks within a Site using the Webhooks REST API. You can write your own code to do this or use Postman API Client tool with our pre-built [Webhooks REST API collection](https://github.com/tableau/webhooks-docs). ## Next Step [Get started](/v0.0/developer/webhooks/en-us/docs/webhooks-get-started.html) # Webhooks Events and Payloads In this topic: ## Trigger Events **Note:** Starting in Tableau 2020.3, the \`event\` attribute of your webhook is the preferred place to specify the triggering event. \`webhook-source\` can also be used or omitted, as long as there is no conflict between the event described in the two elements.    The following events are supported: | `event` Name | `webhook-source` Name | `resource` Name | | --- | --- | --- | | AdminPromoted | webhook-event-user-promoted-admin | USER | | AdminDemoted | webhook-event-user-demoted-admin | USER | | DatasourceUpdated | webhook-source-event-datasource-updated | DATASOURCE | | DatasourceCreated | webhook-source-event-datasource-created | DATASOURCE | | DatasourceDeleted | webhook-source-event-datasource-deleted | DATASOURCE | | DatasourceRefreshStarted | webhook-source-event-datasource-refresh-started | EXTRACTS | | DatasourceRefreshSucceeded | webhook-source-event-datasource-refresh-succeeded | EXTRACTS | | DatasourceRefreshFailed | webhook-source-event-datasource-refresh-failed | EXTRACTS | | LabelCreated | webhook-source-event-label-created | DATASOURCE/WORKBOOK | | LabelUpdated | webhook-source-event-label-updated | DATASOURCE/WORKBOOK | | LabelDeleted | webhook-source-event-label-LabelDeleted | DATASOURCE/WORKBOOK | | SiteCreated | webhook-source-event-site-created | SITE | | SiteUpdated | webhook-source-event-site-updated | SITE | | SiteDeleted | webhook-source-event-site-deleted | SITE | | UserDeleted | webhook-source-event-user-deleted | USER | | ViewDeleted | webhook-source-event-view-deleted | VIEW | | WorkbookUpdated | webhook-source-event-workbook-updated | WORKBOOK | | WorkbookCreated | webhook-source-event-workbook-created | WORKBOOK | | WorkbookDeleted | webhook-source-event-workbook-deleted | WORKBOOK | | WorkbookRefreshStarted | webhook-source-event-workbook-refresh-started | EXTRACTS | | WorkbookRefreshSucceeded | webhook-source-event-workbook-refresh-succeeded | EXTRACTS | | WorkbookRefreshFailed | webhook-source-event-workbook-refresh-failed | EXTRACTS | ### Version Notes - The AdminPromoted and AdminDemoted events are available when connecting to Tableau Cloud and Tableau Server 2021.1 and later.  These events currently only work when updating the user from or to a Site Administrator role. These events do not work to update a user from or to a Server Adminsitrator role. - LabelCreated, LabelUpdated, and LabelDeleted events are available in REST API version 3.16 and when connecting to Tableau Cloud Currently not supported when connecting to Tableau Server. ### Tableau Webhooks Behavior - In some cases, a Tableau event may cause more than one webhook request to be sent to the destination URL server. We recommend that you parse incoming webhook requests to filter duplicates. The JSON payloads of duplicate requests will be identical. - When a server that has been sent a webhook request does not reply with a HTTP success code, the webhook will retry the request three times with diminishing frequency. (A HTTP success code is defined as any number in the [2xx range](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#2xx_Success).) If it still fails after a total of four attempts (fist attempt and 3 retries), the webhook will no longer retry. This is counted as 1 delivery attempt failure. If the same HTTP Post is made again and has a total of 4 such delivery attempt failures, the webhook is automatically disabled and the Webhook owner will be notified using the email address of the account owner on Tableau Server. Any successful attempts will automatically reset the delivery count. A disabled webhook can be manually re-enabled using the [Update a Webhook REST Endpoint](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_webhooks.htm#update_webhook). **This auto-disable behavior is only seen when connecting to Tableau Server version 2021.1**. ## Payloads   When one of the subscribed events fires, a JSON payload is sent to the URL that is configured. The payloads are the same format for all events but the content in the fields varies based on the event type. ### Example Payloads   Here are a few examples of the payloads and what information is included: #### **DatasourceCreated:** ``` { "resource":"DATASOURCE", "event_type":"DatasourceCreated", "resource_name":"My Datasource", "site_luid":"8b2a95d8-52b9-40a4-8712-cd6da771bd1b", "resource_luid":"99", "created_at":"2018-11-15T17:14:45Z" } ``` | Field | Description | | --- | --- | | resource  | “DATASOURCE” | | event\_type  | Type of event that occurred. | | resource\_name  | Name of the datasource in question. | | site\_luid  | LUID for the site that contains the datasource. | | resource\_luid  | The datasource LUID. | | created\_at | The time stamp of when the datasource was created. | #### **Datasource extract refresh:** ``` { "resource":"EXTRACTS", "event_type":"DatasourceRefreshStarted", "resource_name":"My Datasource", "site_luid":"8b2a95d8-52b9-40a4-8712-cd6da771bd1b", "resource_luid":"99", "created_at":"2018-11-15T17:14:45Z" } ``` | Field | Description | | --- | --- | | resource  | “EXTRACTS” | | event\_type  | Type of extract refresh event that occurred. | | resource\_name  | Name of the datasource in question. | | site\_luid  | LUID for the site that contains the datasource. | | resource\_luid  | The datasource LUID. | | created\_at | The time stamp of when the extract refresh job was created. | #### **Workbook created:** ``` { "resource":"WORKBOOK", "event_type":"WorkbookCreated", "resource_name":"My Workbook", "site_luid":"8b2a95d8-52b9-40a4-8712-cd6da771bd1b", "resource_luid":"99", "created_at":"2018-11-15T17:14:45Z" } ``` | Field  | Description  | | --- | --- | | resource  | “WORKBOOK” | | event\_type  | Type of event that occurred. | | resource\_name  | Name of the workbook in question. | | site\_luid  | LUID for the site that contains the workbook. | | resource\_luid  | The workbook LUID. | | created\_at | The time stamp of when the workbook was created. | #### **Workbook extract refresh started:** ``` { "resource":"EXTRACTS", "event_type":"WorkbookRefreshStarted", "resource_name":"My Workbook", "site_luid":"8b2a95d8-52b9-40a4-8712-cd6da771bd1b", "resource_luid":"99", "created_at":"2018-11-15T17:14:45Z" } ``` | Field  | Description  | | --- | --- | | resource  | “EXTRACTS” | | event\_type  | Type of event that occurred. | | resource\_name  | Name of the workbook in question. | | site\_luid  | LUID for the site that contains the workbook. | | resource\_luid  | The workbook LUID. | | created\_at | The time stamp of when the extract refresh job was created. | #### **User Admin Promoted:** ``` { "resource":"USER", "event_type":"AdminPromoted", "resource_name":"Test user", "site_luid":"8b2a95d8-52b9-40a4-8712-cd6da771bd1b", "resource_luid":"25", "created_at":"2018-11-15T17:14:45Z" } ``` | Field  | Description | | --- | --- | | resource  | “USER” | | event\_type  | Type of event that occurred. | | resource\_name  | Name of the user. | | site\_luid  | LUID for the site that the user has permissions to. | | resource\_luid  | The user LUID. | | created\_at | The time stamp of when the user was created. | #### **Label Created for datasource:** ``` { "resource":"DATASOURCE", "event_type":"LabelUpdated", "resource_name":"My Datasource", "site_luid":"8b2a95d8-52b9-40a4-8712-cd6da771bd1b", "resource_luid":"12ab34cd-56ef-78ab-90cd-12ef34ab56cd", "created_at":"2022-05-15T17:14:45Z" } ``` | Field  | Description | | --- | --- | | resource  | DATASOURCE | | event\_type  | Type of event that occurred. | | resource\_name  | Name of the asset in question. | | site\_luid  | LUID for the site that contains the asset. | | resource\_luid  | The asset LUID. | | created\_at | The time stamp of when the label was created. |