Add the changes from OAI#2048 and signpost webhooks

Author: lornajane

versions/3.1.0.md

@@ -1845,6 +1845,8 @@ A map of possible out-of band callbacks related to the parent operation.
 Each value in the map is a [Path Item Object](#pathItemObject) that describes a set of requests that may be initiated by the API provider and the expected responses.
 The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation.
 
+To describe incoming requests from the API provider independent from another API call, use the [`webhooks`](#oasWebhooks) field.
+
 ##### Patterned Fields
 Field Pattern | Type | Description
 ---|:---:|---
@@ -1894,25 +1896,41 @@ $request.body#/successUrls/2 | https://clientdomain.com/medium
 $response.header.Location | https://example.org/subscription/1
 
 
-##### Callback Object Example
+##### Callback Object Examples
 
-The following example shows a callback to the URL specified by the `id` and `email` property in the request body.
+The following example uses the user provided `queryUrl` query string parameter to define the callback URL.  This is an example of how to use a callback object to describe a WebHook callback that goes with the subscription operation to enable registering for the WebHook.
 
 ```yaml
-myWebhook:
-  'https://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}':
+myCallback:
+  '{$request.query.queryUrl}':
     post:
       requestBody:
         description: Callback payload
-        content: 
+        content:
           'application/json':
             schema:
               $ref: '#/components/schemas/SomePayload'
       responses:
         '200':
-          description: webhook successfully processed and no retries will be performed
+          description: callback successfully processed
 ```
 
+The following example shows a callback where the server is hard-coded, but the query string parameters are populated from the `id` and `email` property in the request body.
+
+```yaml
+transactionCallback:
+  'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}':
+    post:
+      requestBody:
+        description: Callback payload
+        content:
+          'application/json':
+            schema:
+              $ref: '#/components/schemas/SomePayload'
+      responses:
+        '200':
+          description: callback successfully processed
+```
 
 #### <a name="exampleObject"></a>Example Object