Merge pull request #2048 from philsturgeon/improved-callback-examples

Improved callback examples

versions/3.0.3.md

@@ -1891,13 +1891,13 @@ $request.body#/successUrls/2 | http://clientdomain.com/medium
 $response.header.Location | http://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:
-  'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}':
+myCallback:
+  '{$request.query.queryUrl}':
     post:
       requestBody:
         description: Callback payload
@@ -1907,9 +1907,25 @@ myWebhook:
               $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