chore: Update the documentation for configuring webhooks in the account (#4703)

swagger/definitions/index.yml

@@ -36,6 +36,8 @@ contactable_inboxes:
   $ref: ./resource/contactable_inboxes.yml
 custom_filter:
   $ref: ./resource/custom_filter.yml
+webhook:
+  $ref: ./resource/webhook.yml
 account:
   $ref: ./resource/account.yml
 platform_account:
@@ -91,6 +93,9 @@ team_create_update_payload:
 custom_filter_create_update_payload:
   $ref: ./request/custom_filter/create_update_payload.yml
 
+webhook_create_update_payload:
+  $ref: ./request/webhooks/create_update_payload.yml
+
 integrations_hook_create_payload:
   $ref: ./request/integrations/hook_create_payload.yml
 
@@ -158,6 +163,3 @@ account_summary:
   $ref: './resource/reports/summary.yml'
 agent_conversation_metrics:
   $ref: './resource/reports/conversation/agent.yml'
-
-
-

swagger/definitions/request/webhooks/create_update_payload.yml

@@ -0,0 +1,18 @@
+type: object
+properties:
+  url:
+    type: string
+    description: The url where the events should be sent
+  subscriptions:
+    type: array
+    items:
+      type: string
+      enum: [
+        "conversation_created",
+        "conversation_status_changed",
+        "conversation_updated",
+        "message_created",
+        "message_updated",
+        "webwidget_triggered"
+      ]
+    description: The events you want to subscribe to.

swagger/definitions/resource/webhook.yml

@@ -0,0 +1,24 @@
+type: object
+properties:
+  id:
+    type: number
+    description: The ID of the webhook
+  url:
+    type: string
+    description: The url to which the events will be send
+  subscriptions:
+    type: array
+    items:
+      type: string
+      enum: [
+        "conversation_created",
+        "conversation_status_changed",
+        "conversation_updated",
+        "message_created",
+        "message_updated",
+        "webwidget_triggered"
+      ]
+    description: The list of subscribed events
+  account_id:
+    type: number
+    description: The id of the account which the webhook object belongs to

swagger/index.yml

@@ -56,17 +56,18 @@ x-tagGroups:
       - Agents
       - Canned Responses
       - Contacts
-      - Conversations
       - Conversation Assignment
       - Conversation Labels
-      - Inboxes
+      - Conversations
-      - Messages
-      - Integrations
-      - Profile
-      - Teams
-      - Custom Filters
-      - Reports
       - Custom Attributes
+      - Custom Filters
+      - Inboxes
+      - Integrations
+      - Messages
+      - Profile
+      - Reports
+      - Teams
+      - Webhooks
   - name: Client
     tags:
       - Contacts API

swagger/parameters/index.yml

@@ -25,6 +25,9 @@ conversation_id:
 custom_filter_id:
   $ref: ./custom_filter_id.yml
 
+webhook_id:
+  $ref: ./webhook_id.yml
+
 message_id:
   $ref: ./message_id.yml
 

swagger/parameters/webhook_id.yml

@@ -0,0 +1,5 @@
+in: path
+name: webhook_id
+type: integer
+required: true
+description: The numeric ID of the webhook

swagger/paths/application/webhooks/create.yml

@@ -0,0 +1,19 @@
+tags:
+  - Webhooks
+operationId: create-a-webhook
+summary: Add a webhook
+description: Add a webhook subscription to the account
+parameters:
+  - $ref: '#/parameters/account_id'
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/webhook_create_update_payload'
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/webhook'
+  401:
+    description: Unauthorized

swagger/paths/application/webhooks/delete.yml

@@ -0,0 +1,12 @@
+tags:
+  - Webhooks
+operationId: delete-a-webhook
+summary: Delete a webhook
+description: Delete a webhook from the account
+responses:
+  200:
+    description: Success
+  401:
+    description: Unauthorized
+  404:
+    description: The webhook does not exist in the account

swagger/paths/application/webhooks/index.yml

@@ -0,0 +1,15 @@
+tags:
+  - Webhooks
+operationId: list-all-webhooks
+summary: List all webhooks
+description:  List all webhooks in the account
+responses:
+  200:
+    description: Success
+    schema:
+      type: array
+      description: 'Array of webhook objects'
+      items:
+        $ref: '#/definitions/webhook'
+  401:
+    description: Unauthorized

swagger/paths/application/webhooks/update.yml

@@ -0,0 +1,19 @@
+tags:
+  - Webhooks
+operationId: update-a-webhook
+summary: Update a webhook object
+description: Update a webhook object in the account
+parameters:
+  - $ref: '#/parameters/account_id'
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/webhook_create_update_payload'
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/webhook'
+  401:
+    description: Unauthorized

swagger/paths/index.yml

@@ -385,6 +385,23 @@
   delete:
     $ref: ./application/custom_filters/delete.yml
 
+# webhooks
+/api/v1/accounts/{account_id}/webhooks:
+  parameters:
+    - $ref: '#/parameters/account_id'
+  get:
+    $ref: ./application/webhooks/index.yml
+  post:
+    $ref: ./application/webhooks/create.yml
+/api/v1/accounts/{account_id}/webhooks/{webhook_id}:
+  parameters:
+    - $ref: '#/parameters/account_id'
+    - $ref: '#/parameters/webhook_id'
+  patch:
+    $ref: ./application/webhooks/update.yml
+  delete:
+    $ref: ./application/webhooks/delete.yml
+
 ### Reports
 
 # List

swagger/swagger.json

@@ -4081,6 +4081,129 @@
         }
       }
     },
+    "/api/v1/accounts/{account_id}/webhooks": {
+      "parameters": [
+        {
+          "$ref": "#/parameters/account_id"
+        }
+      ],
+      "get": {
+        "tags": [
+          "Webhooks"
+        ],
+        "operationId": "list-all-webhooks",
+        "summary": "List all webhooks",
+        "description": "List all webhooks in the account",
+        "responses": {
+          "200": {
+            "description": "Success",
+            "schema": {
+              "type": "array",
+              "description": "Array of webhook objects",
+              "items": {
+                "$ref": "#/definitions/webhook"
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      },
+      "post": {
+        "tags": [
+          "Webhooks"
+        ],
+        "operationId": "create-a-webhook",
+        "summary": "Add a webhook",
+        "description": "Add a webhook subscription to the account",
+        "parameters": [
+          {
+            "$ref": "#/parameters/account_id"
+          },
+          {
+            "name": "data",
+            "in": "body",
+            "required": true,
+            "schema": {
+              "$ref": "#/definitions/webhook_create_update_payload"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "schema": {
+              "$ref": "#/definitions/webhook"
+            }
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
+    },
+    "/api/v1/accounts/{account_id}/webhooks/{webhook_id}": {
+      "parameters": [
+        {
+          "$ref": "#/parameters/account_id"
+        },
+        {
+          "$ref": "#/parameters/webhook_id"
+        }
+      ],
+      "patch": {
+        "tags": [
+          "Webhooks"
+        ],
+        "operationId": "update-a-webhook",
+        "summary": "Update a webhook object",
+        "description": "Update a webhook object in the account",
+        "parameters": [
+          {
+            "$ref": "#/parameters/account_id"
+          },
+          {
+            "name": "data",
+            "in": "body",
+            "required": true,
+            "schema": {
+              "$ref": "#/definitions/webhook_create_update_payload"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "schema": {
+              "$ref": "#/definitions/webhook"
+            }
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      },
+      "delete": {
+        "tags": [
+          "Webhooks"
+        ],
+        "operationId": "delete-a-webhook",
+        "summary": "Delete a webhook",
+        "description": "Delete a webhook from the account",
+        "responses": {
+          "200": {
+            "description": "Success"
+          },
+          "401": {
+            "description": "Unauthorized"
+          },
+          "404": {
+            "description": "The webhook does not exist in the account"
+          }
+        }
+      }
+    },
     "/api/v2/accounts/{account_id}/reports": {
       "parameters": [
         {
@@ -4772,6 +4895,38 @@
         }
       }
     },
+    "webhook": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "number",
+          "description": "The ID of the webhook"
+        },
+        "url": {
+          "type": "string",
+          "description": "The url to which the events will be send"
+        },
+        "subscriptions": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "conversation_created",
+              "conversation_status_changed",
+              "conversation_updated",
+              "message_created",
+              "message_updated",
+              "webwidget_triggered"
+            ]
+          },
+          "description": "The list of subscribed events"
+        },
+        "account_id": {
+          "type": "number",
+          "description": "The id of the account which the webhook object belongs to"
+        }
+      }
+    },
     "account": {
       "type": "object",
       "properties": {
@@ -5223,6 +5378,30 @@
         }
       }
     },
+    "webhook_create_update_payload": {
+      "type": "object",
+      "properties": {
+        "url": {
+          "type": "string",
+          "description": "The url where the events should be sent"
+        },
+        "subscriptions": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "conversation_created",
+              "conversation_status_changed",
+              "conversation_updated",
+              "message_created",
+              "message_updated",
+              "webwidget_triggered"
+            ]
+          },
+          "description": "The events you want to subscribe to."
+        }
+      }
+    },
     "integrations_hook_create_payload": {
       "type": "object",
       "properties": {
@@ -5736,6 +5915,13 @@
       "required": true,
       "description": "The numeric ID of the custom filter"
     },
+    "webhook_id": {
+      "in": "path",
+      "name": "webhook_id",
+      "type": "integer",
+      "required": true,
+      "description": "The numeric ID of the webhook"
+    },
     "message_id": {
       "in": "path",
       "name": "message_id",
@@ -5819,17 +6005,18 @@
         "Agents",
         "Canned Responses",
         "Contacts",
-        "Conversations",
         "Conversation Assignment",
         "Conversation Labels",
-        "Inboxes",
+        "Conversations",
-        "Messages",
+        "Custom Attributes",
-        "Integrations",
-        "Profile",
-        "Teams",
         "Custom Filters",
+        "Inboxes",
+        "Integrations",
+        "Messages",
+        "Profile",
         "Reports",
-        "Custom Attributes"
+        "Teams",
+        "Webhooks"
       ]
     },
     {