From a7ca76ee3e10422b51c7f5a5087e9220131c2638 Mon Sep 17 00:00:00 2001
From: Jordan Woods <13803242+jorwoods@users.noreply.github.com>
Date: Sun, 10 Nov 2024 22:42:01 -0600
Subject: [PATCH] docs: webhook docstrings

---
 tableauserverclient/models/webhook_item.py    | 33 ++++++++
 .../server/endpoint/webhooks_endpoint.py      | 77 +++++++++++++++++++
 2 files changed, 110 insertions(+)

diff --git a/tableauserverclient/models/webhook_item.py b/tableauserverclient/models/webhook_item.py
index 98d821fb..8b551dea 100644
--- a/tableauserverclient/models/webhook_item.py
+++ b/tableauserverclient/models/webhook_item.py
@@ -14,6 +14,39 @@ def _parse_event(events):
 
 
 class WebhookItem:
+    """
+    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.
+
+    Attributes
+    ----------
+    id : Optional[str]
+        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.
+
+    name : Optional[str]
+        The name of the webhook. You must specify this when you create an
+        instance of the WebhookItem.
+
+    url : Optional[str]
+        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.
+
+    event : Optional[str]
+        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. The event name must be one of the supported events
+        listed in the Trigger Events table.
+        https://help.tableau.com/current/developer/webhooks/en-us/docs/webhooks-events-payload.html
+
+    owner_id : Optional[str]
+        The identifier (luid) of the user who owns the webhook.
+    """
+
     def __init__(self):
         self._id: Optional[str] = None
         self.name: Optional[str] = None
diff --git a/tableauserverclient/server/endpoint/webhooks_endpoint.py b/tableauserverclient/server/endpoint/webhooks_endpoint.py
index 06643f99..e5c7b589 100644
--- a/tableauserverclient/server/endpoint/webhooks_endpoint.py
+++ b/tableauserverclient/server/endpoint/webhooks_endpoint.py
@@ -23,6 +23,21 @@ def baseurl(self) -> str:
 
     @api(version="3.6")
     def get(self, req_options: Optional["RequestOptions"] = None) -> tuple[list[WebhookItem], PaginationItem]:
+        """
+        Returns a list of all webhooks on the site.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#list_webhooks_for_site
+
+        Parameters
+        ----------
+        req_options : Optional[RequestOptions]
+            Filter and sorting options for the request.
+
+        Returns
+        -------
+        tuple[list[WebhookItem], PaginationItem]
+            A tuple of the list of webhooks and pagination item
+        """
         logger.info("Querying all Webhooks on site")
         url = self.baseurl
         server_response = self.get_request(url, req_options)
@@ -32,6 +47,21 @@ def get(self, req_options: Optional["RequestOptions"] = None) -> tuple[list[Webh
 
     @api(version="3.6")
     def get_by_id(self, webhook_id: str) -> WebhookItem:
+        """
+        Returns information about a specified Webhook.
+
+        Rest API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#get_webhook
+
+        Parameters
+        ----------
+        webhook_id : str
+            The ID of the webhook to query.
+
+        Returns
+        -------
+        WebhookItem
+            An object containing information about the webhook.
+        """
         if not webhook_id:
             error = "Webhook ID undefined."
             raise ValueError(error)
@@ -42,6 +72,20 @@ def get_by_id(self, webhook_id: str) -> WebhookItem:
 
     @api(version="3.6")
     def delete(self, webhook_id: str) -> None:
+        """
+        Deletes a specified webhook.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#delete_webhook
+
+        Parameters
+        ----------
+        webhook_id : str
+            The ID of the webhook to delete.
+
+        Returns
+        -------
+        None
+        """
         if not webhook_id:
             error = "Webhook ID undefined."
             raise ValueError(error)
@@ -51,6 +95,21 @@ def delete(self, webhook_id: str) -> None:
 
     @api(version="3.6")
     def create(self, webhook_item: WebhookItem) -> WebhookItem:
+        """
+        Creates a new webhook on the site.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#create_webhook
+
+        Parameters
+        ----------
+        webhook_item : WebhookItem
+            The webhook item to create.
+
+        Returns
+        -------
+        WebhookItem
+            An object containing information about the created webhook
+        """
         url = self.baseurl
         create_req = RequestFactory.Webhook.create_req(webhook_item)
         server_response = self.post_request(url, create_req)
@@ -61,6 +120,24 @@ def create(self, webhook_item: WebhookItem) -> WebhookItem:
 
     @api(version="3.6")
     def test(self, webhook_id: str):
+        """
+        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.
+
+        Rest API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#test_webhook
+
+        Parameters
+        ----------
+        webhook_id : str
+            The ID of the webhook to test.
+
+        Returns
+        -------
+        XML Response
+
+        """
         if not webhook_id:
             error = "Webhook ID undefined."
             raise ValueError(error)