From ccf93190d712c27d8c25f9f1b6c280008715cd8d Mon Sep 17 00:00:00 2001
From: Syed Ali Shahbaz <52925846+alishaz-polymath@users.noreply.github.com>
Date: Fri, 10 Mar 2023 22:33:09 +0530
Subject: [PATCH] Swagger docs for webhooks (#245)

This PR updates and adds to the swagger documentation for /webhooks
endpoint
---
 pages/api/webhooks/[id]/_delete.ts | 12 ++++++---
 pages/api/webhooks/[id]/_get.ts    | 12 ++++++---
 pages/api/webhooks/[id]/_patch.ts  | 37 ++++++++++++++++++++++++---
 pages/api/webhooks/_get.ts         | 11 ++++++--
 pages/api/webhooks/_post.ts        | 40 ++++++++++++++++++++++++++++--
 5 files changed, 96 insertions(+), 16 deletions(-)

diff --git a/pages/api/webhooks/[id]/_delete.ts b/pages/api/webhooks/[id]/_delete.ts
index e0e2979ab0..4750741338 100644
--- a/pages/api/webhooks/[id]/_delete.ts
+++ b/pages/api/webhooks/[id]/_delete.ts
@@ -17,12 +17,16 @@ import { schemaQueryIdAsString } from "~/lib/validations/shared/queryIdString";
  *          type: integer
  *        required: true
  *        description: Numeric ID of the hooks to delete
- *     security:
- *       - ApiKeyAuth: []
+ *      - in: query
+ *        name: apiKey
+ *        required: true
+ *        schema:
+ *          type: string
+ *        description: Your API key
  *     tags:
- *     - hooks
+ *     - webhooks
  *     externalDocs:
- *        url: https://docs.cal.com/hooks
+ *        url: https://docs.cal.com/core-features/webhooks
  *     responses:
  *       201:
  *         description: OK, hook removed successfully
diff --git a/pages/api/webhooks/[id]/_get.ts b/pages/api/webhooks/[id]/_get.ts
index 216684cc90..3bde62987a 100644
--- a/pages/api/webhooks/[id]/_get.ts
+++ b/pages/api/webhooks/[id]/_get.ts
@@ -18,12 +18,16 @@ import { schemaWebhookReadPublic } from "~/lib/validations/webhook";
  *           type: integer
  *         required: true
  *         description: Numeric ID of the webhook to get
- *     security:
- *       - ApiKeyAuth: []
+ *       - in: query
+ *         name: apiKey
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Your API key
  *     tags:
- *     - hooks
+ *     - webhooks
  *     externalDocs:
- *        url: https://docs.cal.com/hooks
+ *        url: https://docs.cal.com/core-features/webhooks
  *     responses:
  *       200:
  *         description: OK
diff --git a/pages/api/webhooks/[id]/_patch.ts b/pages/api/webhooks/[id]/_patch.ts
index baa53d257a..35c2810f39 100644
--- a/pages/api/webhooks/[id]/_patch.ts
+++ b/pages/api/webhooks/[id]/_patch.ts
@@ -20,12 +20,41 @@ import { schemaWebhookEditBodyParams, schemaWebhookReadPublic } from "~/lib/vali
  *          type: integer
  *        required: true
  *        description: Numeric ID of the webhook to edit
- *     security:
- *       - ApiKeyAuth: []
+ *      - in: query
+ *        name: apiKey
+ *        required: true
+ *        schema:
+ *          type: string
+ *        description: Your API key
+ *     requestBody:
+ *       description: Edit an existing webhook
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               subscriberUrl:
+ *                 type: string
+ *                 format: uri
+ *                 description: The URL to subscribe to this webhook
+ *               eventTriggers:
+ *                 type: string
+ *                 enum: [BOOKING_CREATED, BOOKING_RESCHEDULED, BOOKING_CANCELLED, MEETING_ENDED]
+ *                 description: The events which should trigger this webhook call
+ *               active:
+ *                 type: boolean
+ *                 description: Whether the webhook is active and should trigger on associated trigger events
+ *               payloadTemplate:
+ *                 type: string
+ *                 description: The template of the webhook's payload
+ *               eventTypeId:
+ *                 type: number
+ *                 description: The event type ID if this webhook should be associated with only that event type
  *     tags:
- *     - hooks
+ *     - webhooks
  *     externalDocs:
- *        url: https://docs.cal.com/hooks
+ *        url: https://docs.cal.com/core-features/webhooks
  *     responses:
  *       201:
  *         description: OK, webhook edited successfully
diff --git a/pages/api/webhooks/_get.ts b/pages/api/webhooks/_get.ts
index 6b00b00e47..8708c303e8 100644
--- a/pages/api/webhooks/_get.ts
+++ b/pages/api/webhooks/_get.ts
@@ -13,10 +13,17 @@ import { schemaWebhookReadPublic } from "~/lib/validations/webhook";
  *   get:
  *     summary: Find all webhooks
  *     operationId: listWebhooks
+ *     parameters:
+ *       - in: query
+ *         name: apiKey
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Your API key
  *     tags:
- *     - hooks
+ *     - webhooks
  *     externalDocs:
- *        url: https://docs.cal.com/webhooks
+ *        url: https://docs.cal.com/core-features/webhooks
  *     responses:
  *       200:
  *         description: OK
diff --git a/pages/api/webhooks/_post.ts b/pages/api/webhooks/_post.ts
index ab8cc028e3..2a99c903e8 100644
--- a/pages/api/webhooks/_post.ts
+++ b/pages/api/webhooks/_post.ts
@@ -9,14 +9,50 @@ import { schemaWebhookCreateBodyParams, schemaWebhookReadPublic } from "~/lib/va
 
 /**
  * @swagger
- * /hooks:
+ * /webhooks:
  *   post:
  *     summary: Creates a new webhook
  *     operationId: addWebhook
+ *     parameters:
+ *       - in: query
+ *         name: apiKey
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Your API key
+ *     requestBody:
+ *       description: Create a new webhook
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required:
+ *               - subscriberUrl
+ *               - eventTriggers
+ *               - active
+ *             properties:
+ *               subscriberUrl:
+ *                 type: string
+ *                 format: uri
+ *                 description: The URL to subscribe to this webhook
+ *               eventTriggers:
+ *                 type: string
+ *                 enum: [BOOKING_CREATED, BOOKING_RESCHEDULED, BOOKING_CANCELLED, MEETING_ENDED]
+ *                 description: The events which should trigger this webhook call
+ *               active:
+ *                 type: boolean
+ *                 description: Whether the webhook is active and should trigger on associated trigger events
+ *               payloadTemplate:
+ *                 type: string
+ *                 description: The template of the webhook's payload
+ *               eventTypeId:
+ *                 type: number
+ *                 description: The event type ID if this webhook should be associated with only that event type
  *     tags:
  *     - webhooks
  *     externalDocs:
- *        url: https://docs.cal.com/webhooks
+ *        url: https://docs.cal.com/core-features/webhooks
  *     responses:
  *       201:
  *         description: OK, webhook created