Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Webhook Profile: Issue 375 - rework notification section #391

Merged
merged 5 commits into from
Apr 19, 2023
Merged

Webhook Profile: Issue 375 - rework notification section #391

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
59deb22
Reorganize Event Connections section
mlagally Apr 17, 2023
c04f62e
new assertion
mlagally Apr 17, 2023
b5e3f08
Update index.html
mlagally Apr 19, 2023
7a683d1
Update index.html
mlagally Apr 19, 2023
ff7ed17
Update index.html
mlagally Apr 19, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 42 additions & 35 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2726,26 +2726,29 @@ <h3>Introduction</h3>
Thus, interactions can be initiated both by the Thing and the Consumer.
</p>
<p>
A Webhook is similar to a callback mechanism in programming languages. Consumers can
subscribe to events they are interested in by registering a listener with the event endpoint.
When the event condition occurs, the WebThing
is notifying all listeners with a corresponding event message, which is transmitted over HTTP(s).
The event message contains details about the event, such as timestamp, event type,
event source etc. in the data payload.
</p><p>
Depending on the deployment scenarios and integration requirements for existing consumers, it may be
required to use specific data payload formats (e.g. Cloud Events).
When a listener receives an event message in a data payload, in many cases it just acknowledges the
successful reception of the event.
Additionally, it may provide a dataResponse payload, which provides a back-channel that can be used
to communicate further details from the consumer to the WebThing.
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).
The notification message contains details about the event, such as timestamp, event type,
event source etc. in the data payload.
</p>

<p>
Depending on the deployment scenarios and integration requirements for existing consumers, it may be
required to use specific data payload formats (e.g. Cloud Events).
When a listener receives an event notification in a data payload, in many cases it just acknowledges the
successful reception of the event.
Additionally, it may provide a dataResponse payload, which provides a back-channel that can be used
to communicate further details from the consumer to the WebThing.
</p>
<p><span class="rfc2119-assertion" id="http-webhook-profile-protocol-binding-events-1">
Depending on the use case, a single listener for multiple things and multiple
event types MAY be used.</span>
endpoints MAY be used.</span>
</p>
<p><span class="rfc2119-assertion" id="http-webhook-profile-protocol-binding-events-2">
To minimize network traffic, the same listerner MUST NOT perform multiple subscriptions to the same listener.</span>
To minimize network traffic, the same Consumer SHOULD NOT perform multiple subscriptions to
the same endpoint.</span>
</p>

<section id="webhook-example">
Expand Down Expand Up @@ -3132,40 +3135,44 @@ <h4><code>unsubscribeallevents</code></h4>
</section>
</section>

<!-- Webhook Notifications -->

<section id="sec-http-webhook-profile-protocol-binding-event-listeners">
<h4>Event Connections</h4>
<h4>Webhook Notifications</h4>

<p>Webhook notifications are sent by the WebThing to registered Consumers to notify them
of value changes of properties or of events occuring on the WebThing.</p>

<p><span class="rfc2119-assertion" id="http-webhook-profile-protocol-binding-event-connections-1">
A HTTP(s) connection to the event listener of a Consumer MUST be initiated and managed by the Web
An HTTP(s) connection to the notification listener of a Consumer MUST be initiated and managed by the Web
Thing.</span>
</p>

<p><span class="rfc2119-assertion" id="http-webhook-profile-protocol-binding-event-connections-1a">
Notifications must be sent with an <code>HTTP POST</code> request with a
<code>Content-Type</code> header set to <code>application/json.</code>
</span>
</p>
<p><span class="rfc2119-assertion" id="http-webhook-profile-protocol-binding-event-connections-2">
A Consumer MUST terminate the subscription with the events endpoint of the Web Thing.</span>
A Consumer MUST actively terminate the subscription to the (event- or property-) endpoint that is sending notifications
of the Web Thing.</span>
</p>
<p><span class="rfc2119-assertion" id="http-webhook-profile-protocol-binding-event-connections-3">
If a Consumer becomes unavailable and the Web Thing cannot successfully transmit
event messages to the consumer, it SHOULD attempt several retries at increasing intervals.</span>
notification messages to the consumer, it SHOULD attempt several retries at increasing intervals.</span>
</p>
<p><span class="rfc2119-assertion" id="http-webhook-profile-protocol-binding-event-connections-4">
After the maximum number of retries was reached, the Web Thing MAY terminate the subscription
without having received an <code>unsubscribe</code> or <code>unsubscribeall</code> operation.</span>
</p>
<p><span class="rfc2119-assertion" id="http-webhook-profile-protocol-binding--event-connections-5">
If the connection between the Web Thing and the Consumer drops,
the Web Thing MUST attempt to re-establish the connection.</span>
</p>
<p><span class="rfc2119-assertion" id="http-webhook-profile-protocol-binding-event-connections-6">
Once the connection is re-established, the Web Thing
SHOULD, if possible, send any missed events which occurred since
the last successful event notification.</span>
</p>
<p><span class="rfc2119-assertion" id="http-webhook-profile-protocol-binding-event-connections-7">
The Web Thing MAY reuse an existing connection to a listener for subsequent message traffic,
or it MAY establish a new connection for each message.</span>
without having received an explicit request corresponding to an <code>unsubscribe</code> or <code>unsubscribeall</code> operation.</span>
</p>

<p><span class="rfc2119-assertion" id="http-webhook-profile-protocol-binding--event-connections-8">
When an event message has been received, the Consumer MUST respond with a "HTTP 200 OK" message.</span>
When a notification message has been received, the Consumer MUST respond with an
<code>HTTP 200 OK</code> response code, if the response contains a body.</span>

<p><span class="rfc2119-assertion" id="http-webhook-profile-protocol-binding--event-connections-8a">
If the response to an notification by the Consumer does not contain a payload, the Consumer MUST respond with an
<code>HTTP 204 No Content</code> response code.</span>

</p>
<p><span class="rfc2119-assertion" id="http-webhook-profile-protocol-binding-event-connections-9">
An (optional) JSON payload MAY be provided to return a response back to the Web Thing
Expand Down