Developer Program Portal

Tutorial

Send a notification when a workbook is created

Difficulty Level
Beginner

Keshia Rose

This tutorial will show you how to set up a webhook that sends a notification to your phone whenever a workbook is created. Webhooks are automated messages sent from Tableau Server/Online when something happens. They have a payload of information and are sent to a specific URL for a receiving web service. Today's web service will be IFTTT's notification service.

Set up the receiving service

First, we need to set up the notification service to be activated based on receiving a webhook message. IFTTT stands for "If This Then That", in our case if a webhook is triggered then send a notification.

  1. If you do not already have an IFTTT account you can sign up for one here.
  2. Once logged in, click on your profile in the top right corner and select Create to create a new applet.
  3. Select this, then search for and select Webhooks.
  4. Choose the trigger of Receive a web request.
  5. Give your event a name, like WorkbookCreated (remember this for later) and click Create trigger.
  6. Select that, then search and select Notifications.
  7. Choose the action Send a rich notification from the IFTTT app.
  8. Edit the title and message that is being sent, they will be generic for now and click Create action. You can add links and images later.
  9. Click Finish.
  10. Download the IFTTT app on your phone and log into your account.

Test the IFTTT setup

Let's make sure that we did it right.

  1. Click on your profile and go to My Services.
  2. Click on Webhooks.
  3. Click on Documentation.
  4. Under "Make a POST or GET web request to:" edit the {event} to what you named your event above. (ex: WorkbookCreated)
  5. Click Test It and you should get a notification!
  6. Copy down the full URL you see under "Make a POST or GET web request to:" as we will need this to set up our webhook in Tableau Server. It should look something like this: https://maker.ifttt.com/trigger/WorkbookCreated/with/key/makF46ZIbtPbEv3CJTal_t

    Note: make sure the event name is in there, it may not copy directly.

Set up the Postman collection

We've set up IFTTT to receive a webhook, we now need to set up Tableau Server to send the webhook to IFTTT. First, let's get the environment set up.

  1. Download and open Postman.
  2. Download the Postman collection for Webhooks (Right-click and Save As).
  3. Click File > Import > Choose Files and choose the Postman collection you downloaded. The collection will then appear on the left.
  4. To configure the variables in the collection, click the cog in the top right corner of the window. This will open the Manage Environments window.
  5. Click Add at the bottom.
  6. Give your environment a name based on the Tableau Server instance you plan to use for this mini-project. If you do not have access to a server you can sign up for a free development sandbox site through our Developer Program!
  7. Next, add the following variables that are specific to your Tableau Server instance. If you are using a server versioned 2019.4 or higher you can use the more secure Personal Access Token (pat-name & pat-secret), otherwise, add username & password.
Variable Current Value
server

https://10ax.online.tableau.com/
username

jamiedata
password

SecureP@$$word
pat-name

demo
pat-secret

1qKESh1AtahNA1bn68+Gg==:fHmahHT2sK2j6eHE3CSHrFakemPpkey3ku

Note: To create a Personal Access Token go to your Tableau Server and click your profile icon in top right. Select My Account Settings, on that page find Personal Access Tokens and type in a name for your token and click Create new token. Copy and take note of the token somewhere as you will not be able to see the token again. 8. Click Add 9. Close the Manage Environments window. 10. Make sure that the dropdown box to the left of the cog you used to open the Manage Environments window is set to the environment you just created. This will populate the variables in the collection with your actual Server values.

Sign in to your server

Authenticate into the Tableau Server.

  1. Drill down on the webhooks collection on the left (this tutorial will be using JSON) and click on the Sign-in item (depending on what variables you set earlier choose the username & password option or the personal access token option), this will create a new tab for your request.
  2. Click on Body and you should see the following (or similar with user/pass):
{
  "credentials": {
     "site": {
        "contentUrl": ""
     },
     "personalAccessTokenName": "{{pat-name}}",
     "personalAccessTokenSecret": "{{pat-secret}}"
  }
}
  1. Add your Tableau Server site content URL to the body.
    Note: the contentUrl is what you see in the address bar when you go to that site on Server. For example: "My Awesome Site" might be "myawesomesite".
{
  "credentials": {
     "site": {
        "contentUrl": "myawesomesite"
     },
     "personalAccessTokenName": "{{pat-name}}",
     "personalAccessTokenSecret": "{{pat-secret}}"
  }
}
  1. Click Send
  2. If everything was successful, below the body you should see a response similar to this:
{
    "credentials": {
        "site": {
            "id": "7ah7244b-g106-f4k3-b5cb-960053c9982qu",
            "contentUrl": "myawesomesite"
        },
        "user": {
            "id": "db9lo9b2-1hg3-46h4-824f-6a09abid109cx"
        },
        "token": "QHUpb3fsRH6AQuQhfharpRQ|UZgGf4k3aAOokMtFaNOfHKd7CcbB0My8QWLf"
    }
}
  1. Take note of the respnse text somewhere as we will need it for subsequent requests.
  2. Open the Manage Environments window again and select your environment to update it. Add the following new variables based on the response text:
Variable Current Value
site-id

7ah7244b-g106-f4k3-b5cb-960053c9982qu
tableau-auth-token

QHUpb3fsRH6AQuQhfharpRQ|UZgGf4k3aAOokMtFaNOfHKd7CcbB0My8QWLf
  1. Click Update and close the window.

Create the webhook

Link to the IFTTT applet from Tableau Server.

  1. Next, let's add variables to our environment for the webhook itself. Open the Manage Environments window again, click on your environment and add the following variables:

Note: you can see a list of the available webhook events in the documentation. The URL is the one that you noted from IFTTT earlier and you can choose any name you like. 2. Click Update and close the window. 3. In the side panel click on the Create a webhook item then click on Body and you should see the following:

{
   "webhook": {
      "webhook-source": {
         "{{webhook-source-api-event-name}}": {}
      },
      "webhook-destination": {
         "webhook-destination-http": {
            "method": "POST",
            "url": "{{webhook-url}}"
         }
      },
      "name": "{{webhook-name}}"
   }
}
  1. The variables will but populated automatically from the variables you just set. You may also notice your tableau-auth-token is being used in the headers.
  2. Click Send. If it was successful you should receive a response like this:
{
    "webhook": {
        "webhook-source": {
            "webhook-source-event-workbook-created": {}
        },
        "webhook-destination": {
            "webhook-destination-http": {
                "method": "POST",
                "url": "https://maker.ifttt.com/trigger/WorkbookCreated/with/key/makF46ZIbtPbEv3CJTal_t"
            }
        },
        "owner": {
            "id": "b9c3217d-t38t-4248-f4k3-97736a2ee9d8",
            "name": "jamiedata"
        },
        "id": "58a6c974-4f5c-f4k3-b766-8c5d877a6d6f",
        "name": "mini_project_1"
    }
}
  1. We want to take note of the id of the webhook and add it to our environment variables. Again, open the Manage Environments window and add a variable called webhook-id with the id you see in the response (ie: 58a6c974-4f5c-f4k3-b766-8c5d877a6d6f). _Note: make sure you grab the webhook id and not the owner id!

Test your webhook

Let's make sure it works.

  1. In the side panel, click on the Test webhook item and click Send.
  2. If it is successful you will receive the following response and should receive a notification on your phone!
{
    "webhookTestResult": {
        "body": "{\"result\": \"success\"}",
        "id": "58a6c974-4f5c-f4k3-b766-8c5d877a6d6f",
        "status": 200
    }
}

Try it out for real

Now let's see it from actual workbook creation.

  1. Either create a workbook in Desktop and publish it to your Server or create a new workbook directly within Server with Web Edit.
  2. If you did everything correctly you should receive a notification! Congratulations!

Challenge exercises

Now that you know the basics of webhooks, try implementing the following bonus challenges.

  1. Change the output method to send an email.
  2. Create a different webhook for data sources being refreshed successfully.

If you would like to check out how to customize the message being sent, check out this sample!

Test in your own Sandbox

Last updated: September 10, 2021