Skip to content

Commit 69737ee

Browse files
kramantabbcantoni
kramantab
and
bcantoni
authored
Adding Webhooks documentation (#1084)
* First Draft for adding webhooks Issue ID #739 TFS ID 1438037 * Adding to TOC, making formatting changes, and updated sample code post testing * Delete Gemfile * Update api-ref.md * Update api-ref.md Removing --- from code blocks per Brain's review * Update api-ref.md Adding a space between "=" and adding a line before print statements * adding spaces before print statement, lower case for webhook (consistency) and recommendation for using short event name * Restore original Gemfile Co-authored-by: Brian Cantoni <bcantoni@salesforce.com>
1 parent decc309 commit 69737ee

3 files changed

Lines changed: 207 additions & 5 deletions

File tree

‎Gemfile‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,2 @@
11
source 'https://rubygems.org'
22
gem 'github-pages', group: :jekyll_plugins
3-

‎_includes/docs_menu.html‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,8 @@
8181
</li>
8282
<li>
8383
<a href="{{ site.baseurl }}/docs/api-ref#views">Views</a>
84+
<li>
85+
<a href="{{ site.baseurl }}/docs/api-ref#webhooks">Webhooks</a>
8486
</li>
8587
<li>
8688
<a href="{{ site.baseurl }}/docs/api-ref#workbooks">Workbooks</a>

‎docs/api-ref.md‎

Lines changed: 205 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4700,21 +4700,222 @@ See [ViewItem class](#viewitem-class)
47004700

47014701

47024702
---
4703+
## Webhooks
4704+
<br>
4705+
<br>
4706+
Using the Tableau Server Client (TSC), you can create a new webhook, get a list of all the webhooks, get details about a specific webhook, or delete a webhook.
4707+
<br>
47034708

4709+
The webhook resource for Tableau Server and Tableau Cloud are defined in the `WebhookItem` class. The class corresponds to the webhook resources you can access using the Tableau REST API. For example, using REST API, you can gather information about a workbook, like the name of the Webbook, the event it is associated with, and the destination URL, and you can get the same information using TSC as well.
4710+
<br>
47044711

4705-
## Workbooks
4712+
Tableau webhook REST API endpoints are available in **REST API version 3.16** and later.
4713+
<br>
4714+
<br>
47064715

4707-
Using the TSC library, you can get information about a specific workbook or all the workbooks on a site, and you can publish, update, or delete workbooks.
4716+
### WebhookItem class
4717+
The `WebhookItem` represents the webhook resources on Tableau Server or Tableau Cloud. This is the information that can be sent or returned in response to a REST API request for webhooks.
47084718

4709-
The project resources for Tableau are defined in the `WorkbookItem` class. The class corresponds to the workbook resources you can access using the Tableau REST API. The workbook methods are based upon the endpoints for projects in the REST API and operate on the `WorkbookItem` class.
4719+
**Attributes**
47104720

4721+
Name | Description
4722+
:--- | :---
4723+
`id` | The identifier (*luid*) for the webhook. You need this value to query a specific webhook with the `get_by_id` method or to delete a webhook with the `delete` method.
4724+
`name` | The name of the webhook. You must specify this when you create an instance of the `WebhookItem`.
4725+
`url` | The destination URL for the webhook. The webhook destination URL must be https and have a valid certificate. You must specify this when you create an instance of the `WebhookItem`.
4726+
`event` | The name of the Tableau event that triggers your webhook.This is either `api-event-name` or `webhook-source-api-event-name`: one of these is required to create an instance of the `WebhookItem`. We recommend using the `api-event-name`. <br> The event name must be one of the supported events listed in the [Trigger Events](https://help.tableau.com/current/developer/webhooks/en-us/docs/webhooks-events-payload.html) table.
4727+
`owner_id` | The identifier of the owner of the webhook.
47114728

4729+
**Example**
47124730

4731+
```py
4732+
import tableauserverclient as TSC
47134733

4734+
# Create new Webhook_item
4735+
4736+
new_webhook = TSC.WebhookItem()
4737+
```
4738+
Source file: models/webhook_item.py
4739+
4740+
<br>
4741+
<br>
4742+
4743+
### Webhook methods
4744+
The Tableau Server Client provides several methods for interacting with webhook resources, or endpoints. These methods correspond to endpoints in the Tableau REST API.
4745+
4746+
Source file: server/endpoint/webhooks_endpoint.py
47144747

47154748
<br>
47164749
<br>
47174750

4751+
#### webhook.create
4752+
```py
4753+
webhooks.create(webhook_item)
4754+
4755+
```
4756+
Creates a new webhook on a specified site.
4757+
4758+
To create a webhook, you must first create a new instance of a `WebhookItem` and pass it to the create method.
4759+
4760+
To specify the site to create the new webhook in, create a `TableauAuth` instance using the content URL for the site `(site_id)` and sign in to that site. For more information on how to specify a site, see the [TableauAuth class](#tableauauth-class).
4761+
4762+
REST API: [Create Webhook](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_notifications.htm#create_webhook)
4763+
4764+
##### **Parmeters**
4765+
4766+
Name | Description
4767+
:--- | :---
4768+
webhook_item | Specifies the properties for the webhook. The webhook_item is the request package. To create a request package, create a new instance of `WebhokItem`. The `WebhookItem` includes the `name`, destination `url`, and the `event` or `source`. The `event` or `source` specifies the Tableau event that should be associated with the webhook.
4769+
4770+
**Returns**
4771+
Returns the new webhook item.
4772+
4773+
**Example**
4774+
```py
4775+
# import tableauserverclient as TSC
4776+
# server = TSC.Server('https://SERVER')
4777+
# sign in . For authentication examples, see https://github.com/tableau/server-client-python/blob/master/samples/login.py
4778+
4779+
# create a webhook item
4780+
with server.auth.sign_in(tableau_auth):
4781+
new_webhook = TSC.WebhookItem()
4782+
new_webhook.name = 'testWebhook'
4783+
new_webhook.event = "workbook-refresh-failed" # alternately, you can also use new_webhook.source="webhook-source-event-workbook-refresh-failed"
4784+
new_webhook.url = "https://webhook.site/6e4c957d-dd40-422c-8fc6-7151afe7fc0b"
4785+
# create the webhook
4786+
new_webhook = server.webhooks.create(new_webhook)
4787+
4788+
print("Webhook created. ID: {}".format(new_webhook.id))
4789+
4790+
```
4791+
<br>
4792+
<br>
4793+
4794+
### webhook.delete
4795+
```py
4796+
webhooks.delete(webhook_id)
4797+
```
4798+
4799+
Deletes a webhook by ID.
4800+
4801+
To specify the site, create a `TableauAuth` instance using the content URL for the site `(site_id)` and sign in to the site. For more information on how to specify a site, see the [TableauAuth class](#tableauauth-class).
4802+
4803+
REST API: [Delete Webhook](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_notifications.htm#delete_webhook)
4804+
4805+
**Parameters**
4806+
4807+
Name|Description
4808+
:---|:---
4809+
`webhook_id`| The ID of the webhook to delete.
4810+
4811+
**Exceptions**
4812+
4813+
Error|Description
4814+
:---|:---
4815+
`Webhook ID undefined`| Raises an exception if a `webhook_id` is not provided.
4816+
4817+
**Example**
4818+
```py
4819+
# import tableauserverclient as TSC
4820+
# server = TSC.Server('https://SERVER')
4821+
# sign in . For authentication examples, see https://github.com/tableau/server-client-python/blob/master/samples/login.py
4822+
4823+
# Delete the webhook
4824+
with server.auth.sign_in(tableau_auth):
4825+
server.webhooks.delete('7d60d364-b9f5-4a9c-8aa5-4bdaa38c5dd3')
4826+
```
4827+
<br>
4828+
<br>
4829+
4830+
#### webhook.get()
4831+
```py
4832+
webhooks.get()
4833+
```
4834+
Returns a list of all the webhooks for a site.
4835+
To specify the site, create a `TableauAuth` instance using the content URL for the site `(site_id)`, and sign in to that site. For more information on how to specify a site, see the [TableauAuth class](#tableauauth-class).
4836+
4837+
REST API: [List Webhooks](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_notifications.htm#list_webhooks_for_site)
4838+
4839+
4840+
**Parameters**
4841+
4842+
Name |Description
4843+
:---|:---
4844+
`req_option`| (Optional) You can pass themthod oa request object that contains additional parameters to filter the request. For example, you could specify the name of the webhook or the name of the owner. For more information, see [Filter and Sort](filter-sort).
4845+
4846+
**Returns**
4847+
4848+
Returns a list of all `ProjectItem` objects and a `PagainationItem`. Use these values to iterate through the results.
4849+
4850+
**Example**
4851+
4852+
```py
4853+
# import tableauserverclient as TSC
4854+
# server = TSC.Server('https://SERVER')
4855+
# sign in . For authentication examples, see https://github.com/tableau/server-client-python/blob/master/samples/login.py
4856+
4857+
# get a list of all the webhooks on a site
4858+
with server.auth.sign_in(tableau_auth):
4859+
all_webhooks, pagination_item = server.webhooks.get()
4860+
4861+
print("\nThere are {} webhooks on site: ".format(pagination_item.total_available))
4862+
print(["Webhook Name:"+ webhook.name+ ";" + "ID:" + webhook.id for webhook in all_webhooks])
4863+
4864+
```
4865+
4866+
#### webhook.get_by_id
4867+
4868+
```py
4869+
webhooks.get_by_ide(webhook_id)
4870+
```
4871+
4872+
Returns information about the specified workbook for a site.
4873+
4874+
To specify the site, create a `TableauAuth` instance using the content URL for the site `(site_id)`, and sign in to that site. For more information on how to specify a site, see the [TableauAuth class](#tableauauth-class).
4875+
4876+
**Parameters**
4877+
4878+
Name|Description
4879+
:---|:---
4880+
`webhook_id`| The ID of the webhook. The ID is a *luid*.
4881+
4882+
**Exceptions**
4883+
4884+
Error|Description
4885+
:---|:---
4886+
`Webhook ID undefined`| Raises an exception if a `webhook_id` is not provided.
4887+
4888+
4889+
**Example**
4890+
```py
4891+
# import tableauserverclient as TSC
4892+
# server = TSC.Server('https://SERVER')
4893+
# sign in . For authentication examples, see https://github.com/tableau/server-client-python/blob/master/samples/login.py
4894+
4895+
with server.auth.sign_in(tableau_auth):
4896+
webhook = server.webhooks.get_by_id ('7d60d364-b9f5-4a9c-8aa5-4bdaa38c5dd3')
4897+
4898+
print (webhook.name, webhook.url)
4899+
4900+
4901+
```
4902+
<br>
4903+
<br>
4904+
4905+
### Additional Resources
4906+
- [REST API Endpoints](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_notifications.htm)
4907+
- [Webhooks Documentation](https://help.tableau.com/current/developer/webhooks/en-us/)
4908+
- [TSC webhooks samples](https://github.com/tableau/server-client-python/blob/master/samples/explore_webhooks.py)
4909+
4910+
---
4911+
## Workbooks
4912+
4913+
Using the TSC library, you can get information about a specific workbook or all the workbooks on a site, and you can publish, update, or delete workbooks.
4914+
4915+
The project resources for Tableau are defined in the `WorkbookItem` class. The class corresponds to the workbook resources you can access using the Tableau REST API. The workbook methods are based upon the endpoints for projects in the REST API and operate on the `WorkbookItem` class.
4916+
4917+
<br>
4918+
47184919
### WorkbookItem class
47194920

47204921
```py
@@ -4816,7 +5017,7 @@ tableau_auth = TSC.TableauAuth('username', 'password', site_id='site')
48165017
server = TSC.Server('https://servername')
48175018

48185019
with server.auth.sign_in(tableau_auth):
4819-
all_workbooks_items, pagination_item = server.workbooks.get()
5020+
all_workbooks_items, pagination_item = server.workbooks.get()
48205021
# print names of first 100 workbooks
48215022
print([workbook.name for workbook in all_workbooks_items])
48225023

0 commit comments

Comments
 (0)