diff --git a/index.html b/index.html index c5e9467..6ba45b3 100644 --- a/index.html +++ b/index.html @@ -2492,7 +2492,7 @@
subscribeevent

If the connection between the Consumer and Web Thing drops - (except as a result of the unsubscribe operation + (except as a result of the unsubscribeevent operation defined below), the Consumer MUST re-establish the connection following the steps outlined in the Server-Sent Events specification [[EVENTSOURCE]]. @@ -2684,13 +2684,13 @@

unsubscribeallevents
- +

HTTP Webhook Profile

This section defines the HTTP Webhook Profile, including a Protocol Binding for observing properties and listening for events using - WebHooks. + Webhooks.

The HTTP Webhook profile MAY be used in conjunction with the @@ -2699,8 +2699,8 @@

HTTP Webhook Profile

cancel actions.

- The HTTP Webhook profile may be used as an alternative event mechanism - to the HTTP SSE Profile. + The HTTP Webhook profile may be used as an alternative event mechanism + to the HTTP SSE Profile.

@@ -2714,19 +2714,18 @@

HTTP Webhook Profile

Introduction

- Webhooks are a mechanism for Consumers to subscribe to events emitted by a Web Thing. + Webhooks can be used as a mechanism for Consumers to subscribe to events and observe properties of a Web Thing.

The mechanism is scalable and supports Consumers that receive events from - multiple Things. Consumers implement a Webhook listener that is handling the event - streams generated by Things. + multiple Things. Consumers implement a Webhook listener which handles events emitted by Things. For Webhook mechanism to function, the Consumer provides a server and client behavior. - The client behavior is used for the initial subscription operation, whereas the server behavior is used to - accept the event streams sent by the Thing. + The client behavior is used for the initial subscription operation, whereas the server behavior is used to accept the events sent by the Thing. Thus, interactions can be initiated both by the Thing and the Consumer.

A Webhook is similar to a callback mechanism in programming languages. Consumers can + subscribe to properties or events they are interested in by registering a listener with that endpoint. When the event condition occurs, the WebThing is notifying all listeners with a corresponding notification, which is transmitted over HTTP(s). @@ -2750,81 +2749,80 @@

Introduction

To minimize network traffic, the same Consumer SHOULD NOT perform multiple subscriptions to the same endpoint.

- +

Webhook Example

- +

The following sequence diagram illustrates the flow of messages between a Consumer and a Web Thing when subscribing to, unsubscribing from and receiving events.

- +
- Webhook example - sequence diagram + Webhook example - sequence diagram
HTTP Webhook Profile - Sequence of operations and notifications
- - + +

The following example contains a snippet from a TD that illustrates how a Webhook event can be described. 

-            ...
-
-            {
-                "events": {
-                    "fireAlarm": {
-                        "title": "Fire Alarm"
-                        "description": "Critical Condition - Fire!",
-                        "subscription": {
+              ...
+  
+              {
+                  "events": {
+                      "fireAlarm": {
+                          "title": "Fire Alarm"
+                          "description": "Critical Condition - Fire!",
+                          "subscription": {
+                              "type": "object",
+                              "properties": {
+                                "callbackURL": {
+                                    "type": "string",
+                                    "format": "uri",
+                                    "description": "Callback URL provided by subscriber for Webhook notifications.",
+                                    "writeOnly": true
+                                },
+                                ...
+                              }
+                          "data": {
+                              "type": "boolean",
+                              "description": "true, if the alert button has been pushed, false, if the button was armed again."
+                          },
+                          "dataResponse": {
+                              "type": "string",
+                              "description": "sprinkler status"
+                          },
+  
+                          "cancellation": {
                             "type": "object",
                             "properties": {
-                              "callbackURL": {
-                                  "type": "string",
-                                  "format": "uri",
-                                  "description": "Callback URL provided by subscriber for Webhook notifications.",
-                                  "writeOnly": true
-                              },
-                              ...
+                                "subscriptionID": {
+                                    "type": "integer",
+                                    "description": "subscription ID to cancel",
+                                    "writeOnly": true
+                                }
                             }
-                        "data": {
-                            "type": "boolean",
-                            "description": "true, if the alert button has been pushed, false, if the button was armed again."
                         },
-                        "dataResponse": {
-                            "type": "string",
-                            "description": "sprinkler status"
-                        },
-
-                        "cancellation": {
-                          "type": "object",
-                          "properties": {
-                              "subscriptionID": {
-                                  "type": "integer",
-                                  "description": "subscription ID to cancel",
-                                  "writeOnly": true
+                        "forms": [
+                              {
+                                  "op": "subscribeevent",
+                                  "href": "http://192.168.0.124:8080/events/fireAlarm/subscribe",
+                                  "contentType": "application/json",
+                                  "htv:methodName": "POST"
+                              },
+                              {
+                                  "op": "unsubscribeevent",
+                                  "href": "http://192.168.0.124:8080/events/fireAlarm/unsubscribe",
+                                  "htv:methodName": "POST"
                               }
-                          }
+                          ]
                       },
-                      "forms": [
-                            {
-                                "op": "subscribeevent",
-                                "href": "http://192.168.0.124:8080/events/fireAlarm/subscribe",
-                                "contentType": "application/json",
-                                "htv:methodName": "POST"
-                            },
-                            {
-                                "op": "unsubscribeevent",
-                                "href": "http://192.168.0.124:8080/events/fireAlarm/unsubscribe",
-                                "htv:methodName": "POST"
-                            }
-                        ]
-                    },
-                    "batteryLow": {
-                        ...
-                    }
-                }
-            }
-
+ "batteryLow": { + ... + } + } + } +
@@ -2843,19 +2841,19 @@

Identifier

profile entries, which indicates that a Web Thing conforms to all of the profiles in that array.

- -
+ +

Message Format

-

- Event notification messages MUST comply with the following data schema. +

+ Notification messages MUST comply with the following data schema.

- +

TODO: Describe data and dataResponse schemas.

- +

Protocol Binding

@@ -2870,12 +2868,302 @@

Protocol Binding

A Consumer or Web Thing conforming to the HTTP Webhook Profile MUST implement this protocol binding.

+ + +
+

Properties

+
+

observeproperty

+
+

+ The URL of a Property resource to be used when + observing the value of a property MUST be obtained from a Thing + Description by locating a + + Form inside the corresponding + + PropertyAffordance + for which: +

+
    +
  • + Its op member contains the value + observeproperty +
    • +
  • + After being resolved against a base URL where applicable, the + URI + scheme [[RFC3986]] of the value of its href + member is http or https +
    • +
  • Its Content-Type header has a value of + application/json +
    • +
  • Its subprotocol member has a value of + webhook +
    • +
+
+

+ + The resolved value of the href member MUST then be + used as the URL of the Property resource. +

+

+ + In order to observe a property, a Consumer MUST + provide the listener URL in the request payload of the + observeproperty operation of the Property resource. +

+

+ This involves the Consumer sending an HTTP request to + the Web Thing with: +

+
    +
  • Method set to POST
    • +
  • URL set to the URL of the Property resource
    • +
  • + Content-Type header set to application/json +
    • +
  • + A body with a subscription request payload, serialized in JSON. +
    • +

    + The subscription payload contains the URI for the notification listener + in the field with the callbackURI key. +

    +
+ 
+              POST /things/lamp/properties/level HTTP/1.1
+              Host: mythingserver.com
+              Content-Type: application/json
+              {
+                callbackURI: "http://myConsumer.com/myNotificationListener"
+              }
+
+ +

+ If a Web Thing receives an HTTP request following the format + above and the Consumer has permission to observe the + corresponding property, then it MUST send a notification + to the Consumer each time the value of the specified property changes. +

+ +

+ This involves the Web Thing initially sending an HTTP + response to the Consumer with: +

+
    +
  • Status code set to 201 Created
    • +
  • + Content-Type header set to + application/json +
    • +
  • + Location header set to the URL of the Event resource + followed by a unique subscriptionId +
    • +
+ 
+              HTTP/1.1 201 Created
+              Content-Type: application/json
+              Location: /things/properties/level/1234-4544-1211
+
+

+ Whenever a change of the property occurs, the Web Thing MUST + send the new value to the Consumer with an HTTP POST request with a + Content-Type header set to application/json, + in the payload format defined in section + ["#http-webhook-profile-protocol-binding-notification-format"]. +

+ +
+ +
+

unobserveproperty

+ +

+ + In order to stop observing a property, a Consumer MUST terminate + the corresponding subscription with the Web Thing using the + unobserveproperty operation of the Property resource. + +

+ +

+ This involves the Consumer sending an HTTP request to + the Web Thing with: +

+
    +
  • Method set to DELETE
    • +
  • URL set to the subscription URL + provided in the Location header + of the response to the subscribe request
    • +
-
-

Operations

+

+ If a Web Thing receives an HTTP request following the format + above and the Consumer has subscribed to the + corresponding property with the subscriptionID provided, + then the subscription is cancelled. +

-
-

subscribeevent

+

+ This involves the Web Thing sending an HTTP + response to the Consumer with: +

+
    +
  • Status code set to 204 No Content
    • +
+ 
+          HTTP/1.1 204 No Content
+
+
+ +
+

observeallproperties

+
+

+ The URL of a Properties resource to be used when observing + changes to all properties of a Web Thing MUST be obtained from a + Thing Description by locating a + + Form inside the top level + forms + member of a Thing Description for which: +

+
    +
  • + Its op member contains the value + observeallproperties +
    • +
  • + After being resolved against a base URL where applicable, the + URI + scheme [[RFC3986]] of the value of its href + member is http or https +
    • +
  • Its Content-Type header has a value of + application/json +
    • +
  • Its subprotocol member has a value of + webhook +
    • +
+
+

+ + The resolved value of the href member MUST then be + used as the URL of the properties resource. +

+

+ + In order to observe changes to all properties of a Web Thing, a + Consumer MUST send an HTTP request to the Web Thing with: +

+
    +
  • Method set to POST
    • +
  • URL set to the URL of the properties resource
    • +
  • + Content-Type header set to application/json +
    • +
  • + Request Payload contains a JSON + object with a subscription request payload. +
    • + +
+ 
+            POST /things/lamp/properties HTTP/1.1
+            Host: mythingserver.com
+            Content-Type: application/json
+  
+            {
+              callbackURI: "http://myConsumer.com/myNotificationListener"
+            }
+
+ +

+ If a Web Thing receives an HTTP request following the format + above, then it MUST send notification + to the Consumer for all properties for which it has permission to subscribe. +

+

+ This involves the Web Thing initially sending an HTTP + response to the Consumer with: +

+
    +
  • Status code set to 201 Created
    • +
  • + Content-Type header set to + application/json +
    • +
  • + Location header set to the URL of the Property resource + followed by a unique subscriptionId +
    • +
+ + 
+            HTTP/1.1 201 Created
+            Content-Type: application/json
+            Location: /things/lamp/properties/1234-4544-1211
+
+ +

+ Whenever a property changes while a Consumer is oberving Properties, + the Web Thing MUST send the new value to the Consumer with an + HTTP POST request with a + Content-Type header set to application/json, + and the payload format defined in section + ["#http-webhook-profile-protocol-binding-notification-format"]. +

+ +
+

unobserveallproperties

+

+ +

+ In order to unobserve all properties, a Consumer MUST invoke the + unobserveallproperties operation of the Property resource. +

+ +
Todo: Need to provide the subscriptionID either in payload or URL
+

+ This involves the Consumer sending an HTTP request to + the Web Thing with: +

+
    +
  • Method set to DELETE
    • +
  • URL set to the subscription URL + provided in the Location header + of the response to the subscribeallevents request. +
    • +
+ 
+              DELETE /things/lamp/properties/1234-4544-1211 HTTP/1.1
+              Host: mythingserver.com
+
+ +

+ This involves the Web Thing sending an HTTP + response to the Consumer with: +

+
    +
  • Status code set to 204 No Content
    • +
+ 
+              HTTP/1.1 204 No Content
+
+
+
+ + + +
+

Events

+
+

subscribeevent

The URL of an Event resource to be used when @@ -2897,6 +3185,9 @@

subscribeevent

scheme [[RFC3986]] of the value of its href member is http or https +
  • Its Content-Type header has a value of + application/json +
  • Its subprotocol member has a value of webhook
    • @@ -2915,11 +3206,11 @@

    subscribeevent

    This involves the Consumer sending an HTTP request to the Web Thing with:

    -
      +
        git
      • Method set to POST
      • URL set to the URL of the Event resource
      • - Accept header set to application/json + Content-type header set to application/json
      • A body with a subscription request payload, serialized in JSON. @@ -2928,16 +3219,14 @@

        subscribeevent

        The subscription payload contains the URI for the event message listener in the field with the callbackURI key.

        - 
                     POST /things/lamp/events/overheated HTTP/1.1
               Host: mythingserver.com
               Content-Type: application/json
-              Accept: application/json
               {
                 callbackURI: "http://myConsumer.com/myEventListener"
-            }
+              }

      @@ -2952,38 +3241,34 @@

      subscribeevent

      response to the Consumer with:

        -
      • Status code set to 200
        • +
      • Status code set to 201 Created
      • Content-Type header set to application/json
      • - Accept header set to application/json + Location header set to the URL of the Event resource + followed by a unique subscriptionId 
      -              HTTP/1.1 200 OK
-              Content-Type: application/json
-              {
-                  subscriptionId: 1234-4544-1211
-              }
-
-
      + HTTP/1.1 201 Created + Location: /things/lamp/events/overheated/1234-4544-1211 +

      Whenever an event of the specified type occurs, the Web Thing MUST send event data to the Consumer using the event payload format defined in section - ["#sec-http-webhook-profile-protocol-binding-events-notification"]. + ["#sec-http-webhook-profile-protocol-binding-notification"].

      -

    unsubscribeevent

    -

    +

    In order to unsubscribe to an event, a Consumer MUST - provide the subscriptionID in the data payload of the - unsubscribe operation of the Event resource. + terminate the corresponding subscription with the Web Thing using the + unsubscribeevent operation of the Event resource.

    This involves the Consumer sending an HTTP request to @@ -2991,12 +3276,25 @@

    unsubscribeevent

    • Method set to DELETE
      • -
    • URL set to the URL of the Event resource followed by the subscriptionId of a valid subscription
      • -
    • - Accept header set to application/json -
      • +
    • URL set to the subscription URL + provided in the Location header + of the response to the subscribe request
    +

    + If a Web Thing receives an HTTP request following the format + above and the Consumer has subscribed to the + corresponding event with the subscriptionID provided, + then the subscription is cancelled. +

    + +

    + This involves the Web Thing sending an HTTP + response to the Consumer with: +

    +
      +
    • Status code set to 204 No Content
      • + 
                 DELETE /things/lamp/events/overheated/1234-4544-1211 HTTP/1.1
             Host: mythingserver.com
@@ -3026,6 +3324,9 @@ 
    subscribeallevents
    
                   scheme [[RFC3986]] of the value of its href
                 member is http or https
               
+              
  • Its Content-Type header has a value of
+                application/json
+              
    • 
               
  • Its subprotocol member has a value of
                 webhook
               
    • 
@@ -3044,7 +3345,7 @@ 
    subscribeallevents
    
               
  • Method set to POST
    • 
               
  • URL set to the URL of the events resource
    • 
               
  • 
-                Accept header set to application/json
+                Content-Type header set to application/json
               
    • 
               
  • 
                 Request Payload contains a JSON
@@ -3055,7 +3356,7 @@ 
    subscribeallevents
    
           
                 POST /things/lamp/events HTTP/1.1
             Host: mythingserver.com
-            Accept: application/json
+            Content-Type: application/json
 
             {
               callbackURI: "http://myConsumer.com/myEventListener"
@@ -3073,29 +3374,26 @@ 
    subscribeallevents
    
             response to the Consumer with:
           
    
           
      
-            
    • Status code set to 200
      • 
+            
    • Status code set to 201 Created
      • 
             
    • 
               Content-Type header set to
               application/json
             
      • 
             
    • 
-              Accept header set to application/json
+              Location header set to the URL of the Event resource
+              followed by a unique subscriptionId
             
      • 
-            
    • Response payload contains a JSON object with a subscriptionId.
      • 
           
    
-
           
    -          HTTP/1.1 200 OK
-          Content-Type: application/json
-          {
-            subscriptionId: 1234-4544-1211
-          }
+            HTTP/1.1 201 Created
+            Content-Type: application/json
+            Location: /things/lamp/events/overheated/1234-4544-1211
           
    
 
           
    
               Whenever an event occurs, the Web Thing MUST send event data to the Consumer
               using the event payload format defined in section Message Format.
+                href="sec-http-webhook-profile-notification-format">Notification Format.
 
           
    
               If the connection between the Web Thing and the Consumer drops,
@@ -3113,25 +3411,43 @@ 
    subscribeallevents
    
           
    unsubscribeallevents
    
           
    
               In order to unsubscribe from all events, a Consumer MUST invoke the
-              unsubscribe operation of the Event resource.
+              unsubscribeevent operation of the Event resource.
           
    
 
+          
    
+            If a Web Thing receives an HTTP request following the format
+            above and the Consumer has subscribed to the
+            corresponding event with the subscriptionID provided, 
+            then the subscription is cancelled.
+          
    
           
    
             This involves the Consumer sending an HTTP request to
             the Web Thing with:
           
    
           
      
             
    • Method set to DELETE
      • 
-            
    • URL set to the URL of the Event resource
      • 
-            
    • 
-              Accept header set to application/json
-            
      • 
+            
    • URL set to the subscription URL 
+              provided in the Location header 
+              of the response to the subscribeallevents request.
      • 
           
    
 
             
                   DELETE /things/lamp/events HTTP/1.1
               Host: mythingserver.com
             
    
+
+            
    
+              This involves the Web Thing sending an HTTP
+              response to the Consumer with:
+            
    
+            
      
+              
    • Status code set to 204 No Content
      • 
+            
    
+              
    +                DELETE /things/lamp/events/1234-4544-1211 HTTP/1.1
+                Host: mythingserver.com
+              
    
+