Webhook subscription mechanism #325
Conversation
mlagally
requested review from
benfrancis,
mmccool,
egekorkan and
sebastiankb
|
Arch call on Nov 23rd:
|
|
Created issue #329 to address the issue wrt. normative text for the entire spec. |
|
Arch call on Dec 7th: |
| 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. |
| <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 |
| 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). |
There was a problem hiding this comment.
This is true for Webhooks in general, but not for profiles which are designed for greenfield deployments.
This specification should define its own payload format, see #258
| <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> | ||
| </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> |
There was a problem hiding this comment.
listerner -> listener
This assertion doesn't make sense. Why would a listener subscribe to a listener?
| @@ -3046,26 +3054,22 @@ <h4><code>subscribeevent</code></h4> | |||
| <code>Accept</code> header set to <code>application/json</code> | |||
| </li> | |||
| <li> | |||
| A body with a subscription payload, serialized in JSON. | |||
| A body with a subscription request payload, serialized in JSON. | |||
There was a problem hiding this comment.
Should also mention Content-Type header set to application/json, since the request has a JSON payload.
| <li>Method set to <code>POST</code></li> | ||
| <li>URL set to the URL of the <code>Event</code> resource</li> | ||
| <li>Method set to <code>DELETE</code></li> | ||
| <li>URL set to the URL of the <code>Event</code> resource followed by the <code>subscriptionId</code> of a valid subscription</li> |
There was a problem hiding this comment.
Example 44 uses subscriptionID, but this says subscriptionId.
There was a problem hiding this comment.
What should the response be? I would suggest 204 No Content, as with the cancelaction protocol binding in the HTTP Basic Profile. This would also mean no Accept header is needed on this request.
| <code>Accept</code> header set to <code>application/json</code> | ||
| </li> |
There was a problem hiding this comment.
I don't think the Accept header is necessary here is it?
| </ul> | ||
|
|
||
| <pre class="example" title="Unsubscribe using subscriptionId"> | ||
| DELETE /things/lamp/events/overheated/1234-4544-1211 HTTP/1.1 |
There was a problem hiding this comment.
Assertion http-webhook-profile-protocol-binding-subscribeevent-4b says that the subscription ID should be sent in the payload, but here it is included in the URL. I agree it should be in the URL.
| <code>Accept</code> header set to <code>application/json</code> | ||
| </li> |
There was a problem hiding this comment.
Responses don't need Accept headers.
| </p> | ||
|
|
||
| <pre class="example" title="Unsubscribe all using callbackURI"> | ||
| DELETE /things/lamp/events HTTP/1.1 |
There was a problem hiding this comment.
The request URL should include the subscription ID.
Preview | Diff