From 11ea8a3032a7199c71308fbcc5d52056d73412a9 Mon Sep 17 00:00:00 2001 From: Pranav Raj S Date: Thu, 19 May 2022 21:43:23 +0530 Subject: [PATCH] chore: Update the documentation for configuring webhooks in the account (#4703) --- swagger/definitions/index.yml | 8 +- .../webhooks/create_update_payload.yml | 18 ++ swagger/definitions/resource/webhook.yml | 24 +++ swagger/index.yml | 17 +- swagger/parameters/index.yml | 3 + swagger/parameters/webhook_id.yml | 5 + swagger/paths/application/webhooks/create.yml | 19 ++ swagger/paths/application/webhooks/delete.yml | 12 ++ swagger/paths/application/webhooks/index.yml | 15 ++ swagger/paths/application/webhooks/update.yml | 19 ++ swagger/paths/index.yml | 17 ++ swagger/swagger.json | 201 +++++++++++++++++- 12 files changed, 340 insertions(+), 18 deletions(-) create mode 100644 swagger/definitions/request/webhooks/create_update_payload.yml create mode 100644 swagger/definitions/resource/webhook.yml create mode 100644 swagger/parameters/webhook_id.yml create mode 100644 swagger/paths/application/webhooks/create.yml create mode 100644 swagger/paths/application/webhooks/delete.yml create mode 100644 swagger/paths/application/webhooks/index.yml create mode 100644 swagger/paths/application/webhooks/update.yml diff --git a/swagger/definitions/index.yml b/swagger/definitions/index.yml index c06dd1471..5e22a7099 100644 --- a/swagger/definitions/index.yml +++ b/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' - - - diff --git a/swagger/definitions/request/webhooks/create_update_payload.yml b/swagger/definitions/request/webhooks/create_update_payload.yml new file mode 100644 index 000000000..417843fe6 --- /dev/null +++ b/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. diff --git a/swagger/definitions/resource/webhook.yml b/swagger/definitions/resource/webhook.yml new file mode 100644 index 000000000..1e4c58904 --- /dev/null +++ b/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 diff --git a/swagger/index.yml b/swagger/index.yml index b2dd91e46..f64a090e7 100644 --- a/swagger/index.yml +++ b/swagger/index.yml @@ -56,17 +56,18 @@ x-tagGroups: - Agents - Canned Responses - Contacts - - Conversations - Conversation Assignment - Conversation Labels - - Inboxes - - Messages - - Integrations - - Profile - - Teams - - Custom Filters - - Reports + - Conversations - Custom Attributes + - Custom Filters + - Inboxes + - Integrations + - Messages + - Profile + - Reports + - Teams + - Webhooks - name: Client tags: - Contacts API diff --git a/swagger/parameters/index.yml b/swagger/parameters/index.yml index d69640369..2c61a6a01 100644 --- a/swagger/parameters/index.yml +++ b/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 diff --git a/swagger/parameters/webhook_id.yml b/swagger/parameters/webhook_id.yml new file mode 100644 index 000000000..4400a082c --- /dev/null +++ b/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 diff --git a/swagger/paths/application/webhooks/create.yml b/swagger/paths/application/webhooks/create.yml new file mode 100644 index 000000000..e4d3053ee --- /dev/null +++ b/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 diff --git a/swagger/paths/application/webhooks/delete.yml b/swagger/paths/application/webhooks/delete.yml new file mode 100644 index 000000000..525c22dfc --- /dev/null +++ b/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 diff --git a/swagger/paths/application/webhooks/index.yml b/swagger/paths/application/webhooks/index.yml new file mode 100644 index 000000000..f96fa00de --- /dev/null +++ b/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 diff --git a/swagger/paths/application/webhooks/update.yml b/swagger/paths/application/webhooks/update.yml new file mode 100644 index 000000000..b395e7362 --- /dev/null +++ b/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 diff --git a/swagger/paths/index.yml b/swagger/paths/index.yml index 2175a3154..084065a9a 100644 --- a/swagger/paths/index.yml +++ b/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 diff --git a/swagger/swagger.json b/swagger/swagger.json index ec1bf8a25..9103fe13e 100644 --- a/swagger/swagger.json +++ b/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", - "Messages", - "Integrations", - "Profile", - "Teams", + "Conversations", + "Custom Attributes", "Custom Filters", + "Inboxes", + "Integrations", + "Messages", + "Profile", "Reports", - "Custom Attributes" + "Teams", + "Webhooks" ] }, {