Add Code Snippets to Spec Files

Author: DX-Bandwidth

site/specs/numbers.yml

@@ -1043,38 +1043,31 @@ components:
       description: Verification callback status of a toll-free phone number.
       required: true
     webhookSubscriptionRequest:
-      properties:
-        accountId:
-          type: string
-        basicAuthentication:
-          properties:
-            password:
-              maxLength: 200
-              type: string
-            username:
-              maxLength: 100
-              type: string
-          required:
-            - username
-            - password
-          type: object
-        callbackUrl:
-          $ref: '#/components/schemas/webhookUrl'
-        createdDate:
-          format: date-time
-          type: string
-        id:
-          type: string
-        modifiedDate:
-          format: date-time
-          type: string
-        type:
-          enum:
-            - TOLLFREE_VERIFICATION_STATUS
-          type: string
-      required:
-        - callbackUrl
-      type: object
+      content:
+        application/json:
+          schema:
+            properties:
+              basicAuthentication:
+                properties:
+                  password:
+                    maxLength: 200
+                    type: string
+                  username:
+                    maxLength: 100
+                    type: string
+                required:
+                  - username
+                  - password
+                type: object
+              callbackUrl:
+                $ref: '#/components/schemas/webhookUrl'
+            required:
+              - callbackUrl
+            type: object
+      description: >-
+        Information about a webhook that Bandwidth should send upon the
+        completion of TFV verification.
+      required: true
     zipWhipTfvWebhookRequest:
       content:
         application/json:
@@ -1343,21 +1336,21 @@ components:
       content:
         application/json:
           schema:
-            $ref: '#/components/requestBodies/webhookSubscriptionRequest'
+            $ref: '#/components/schemas/webhookSubscription'
       description: Created
     webhookSubscriptionDeleted:
       description: Deleted
     webhookSubscriptionUpdated:
       content:
         application/json:
           schema:
-            $ref: '#/components/requestBodies/webhookSubscriptionRequest'
+            $ref: '#/components/schemas/webhookSubscription'
       description: OK
     webhookSubscriptionsList:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/webhookSubscriptionsApiPage'
+            $ref: '#/components/schemas/webhookSubscriptionsListBody'
       description: OK
   schemas:
     A2pClass:
@@ -14264,11 +14257,6 @@ components:
         verificationRequestId:
           example: abc-d8569gh
           type: string
-        webhookUrl:
-          example: https://your_url.com/webhookService
-          pattern: >-
-            ^$|(https?:\/\/)?(www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,253}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#()?&//=]*)
-          type: string
       type: object
     useCase:
       example: 2FA
@@ -14331,8 +14319,6 @@ components:
           minLength: 0
           nullable: false
           type: string
-        webhookUrl:
-          $ref: '#/components/schemas/webhookUrl'
       required:
         - businessAddress
         - businessContact
@@ -14365,24 +14351,71 @@ components:
         status:
           $ref: '#/components/schemas/tfvCallbackStatus'
       type: object
-    webhookSubscriptionsApiPage:
+    webhookSubscription:
       description: >-
-        Object that returns the full list of webhook subscriptions for an
-        account.
+        Information about a webhook that Bandwidth should send upon the
+        completion of TFV verification.
+      properties:
+        accountId:
+          example: '1234567'
+          type: string
+        basicAuthentication:
+          description: >-
+            Basic authentication credentials are not required, but if present,
+            both username and password must be provided.
+          properties:
+            password:
+              maxLength: 200
+              type: string
+            username:
+              maxLength: 100
+              type: string
+          required:
+            - username
+            - password
+          type: object
+        callbackUrl:
+          $ref: '#/components/schemas/webhookUrl'
+        createdDate:
+          example: '2023-05-15T13:56:39.965Z'
+          format: date-time
+          type: string
+        id:
+          example: 7hICGStfAfeGxEq3N0lQwO
+          type: string
+        modifiedDate:
+          example: '2023-05-15T13:56:39.965Z'
+          format: date-time
+          type: string
+        type:
+          description: >-
+            Currently only one type of webhook is supported for toll-free
+            verification, and that is the webhook for the status of a toll-free
+            verification request.
+          enum:
+            - TOLLFREE_VERIFICATION_STATUS
+          type: string
+      required:
+        - callbackUrl
+      type: object
+    webhookSubscriptionsListBody:
+      description: >-
+        A list of all webhook subscriptions registered for this account ID for
+        this particular feature (unpaginated).
       properties:
         data:
           items:
-            $ref: '#/components/requestBodies/webhookSubscriptionRequest'
+            $ref: '#/components/schemas/webhookSubscription'
           type: array
-        type: object
+      required:
+        - data
+      type: object
     webhookUrl:
       description: >-
-        Callback URL to receive status updates from Bandwidth. When this value
-        is registered with a validation request, it will be used for that
-        request (only) and it cannot be updated after submission. To register a
-        callback for all status updates, which can be updated through the API,
-        register a webhook subscription (which can also include basic
-        authentication credentials).
+        Callback URL to receive status updates from Bandwidth. When a webhook
+        subscription is registered with Bandwidth under a given account ID, it
+        will be used to send status updates for all requests submitted under
+        that account ID.
       example: https://www.example.com/path/to/resource
       maxLength: 2000
       minLength: 0
@@ -40148,12 +40181,11 @@ paths:
     post:
       description: >-
         Create a new webhook subscription (this webhook will be called for every
-        update on every submission; is is also possible to register a one-time
-        callback URL as part of a submission itself). In addition to a
-        `callbackUrl`, this subscription can provide HTTP Basic authentication
-        credentials (a username and a password). The returned subscription
-        object will contain an ID that can be used to modify or delete the
-        subscription at a later time.
+        update on every submission). In addition to a `callbackUrl`, this
+        subscription can provide optional HTTP basic authentication credentials
+        (a username and a password). The returned subscription object will
+        contain an ID that can be used to modify or delete the subscription at a
+        later time.
       operationId: createWebhookSubscription
       parameters:
         - $ref: '#/components/parameters/AccountIdPathParam'