From 35b24038968d1485b9b13488a6857e672ca56c4b Mon Sep 17 00:00:00 2001
From: Lorna Jane Mitchell <lorna@lornajane.net>
Date: Tue, 14 Jan 2020 11:55:24 +0000
Subject: [PATCH] Add the changes from #2048 and signpost webhooks

---
 versions/3.1.0.md | 30 ++++++++++++++++++++++++------
 1 file changed, 24 insertions(+), 6 deletions(-)

diff --git a/versions/3.1.0.md b/versions/3.1.0.md
index 9efd1253bc..a389504a31 100644
--- a/versions/3.1.0.md
+++ b/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