Webhooks Methods

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

  • Create a new Webhook for a site.
  • Delete a Webhook.
  • Get a list of Webhooks for a specific site.
  • Return information about a specific Webhook.
  • Test a Webhook.
  • Update a Webhook.

To learn about what Webhooks are and how to use them, see the Tableau Webhooks guide.

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 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.11/sites/site-id/webhooks/<new-webhook-id>

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 administrators.

Response Code

204

Response Body

None.

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 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>

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 administrators.

Response Code

200

Response Body

<tsResponse>

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

    <body></body>

  </webhookTestResult>

</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 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.11/sites/site-id/webhooks/new-webhook-id


Thanks for your feedback!