WebHook Event Subscription

[RobPhippen]

Summary

This issue proposes a mechanism to allow an event subscription API to be associated with the stream of events that may occur as a 'side effect' of the subscription.

This is one of three items agreed to be split out from #716 (see this note).

Objective of the proposal

• Subcription/Publication association: allow a programmer to discover the events that can occur once they have registered

Background

Many SaaS systems provide some kind of event interface as core to their behaviour.
There are many approaches to implementing this. No single approach is as prevalent as JSON/HTTP APIs have become for service implementation however webhooks is significtly more common than any other single approach.

WebHooks

Webhooks are a convention of use of normal Web interfaces, typically using JSON/HTTP,
in which an event subscriber can register a callback URL with an event publisher.
When an event occurs, the event publisher invokes an HTTP method on that URL (Typically POST) to send the information related to the event.

WebHooks in real life

Webhooks are not standardized nor formally specified, but are in common use in a substiantial
number of systems.

The lack of standardisation means that there is variation in each of the following
areas;

• Whether or not a subscription API is made available - many systems instead require
  registration via an administrative UI
• If a subscription API is available, its precise form varies between different systems
• Some systems effectively require a different callback URL to be registered for each event stream,
  while others support subscription to multiple event streams with a single callback URL

The following conventions are commonly observed;

• When an event occurs, where the publisher supports subscription to multiple different event streams on the same URL
  it is common for them to provide a parameter, or a data field within a parameter, as part of the
  POSTed message that specifies which event has occurred.
• When an event occurs, almost all systems support the use of HTTP POST to convey the event information.
  Some mandate the use of HTTP POST, while others allow other HTTP methods to be selected as an option

Scope of this proposal

This proposal covers the particular case where

• a webhooks subscription API is offered that allows a callback URL to be registered, and which allows the event of interest to be specified
• a single subscription results in a single logical event stream being delivered to the registered callback URL

The proposal does not specify a standardised form for the subscription API. Instead, it enables a subscription API to be identified via the presence of the x-event-streams element, which models the event stream that occurs as a result of the subscription operation.

Related Proposals

An additional proposal, #736, builds on this proposal to add a mechanism to discriminate between multiple logical event streams on the same physical callback address.

Proposed Swagger Syntax

New syntax elements

This proposal introduces a single new syntax element, x-event-streams.
This is defined to be an array in which each element defines a single logical event stream.
The event stream is delivered to the callback URL registered against the subscription API.
In the absence of #736, this array is constrained to contain only one element.

x-event-streams contains the following elements;

• event-id, a logical identifier for the event
• description, a textual description of the event stream
• parameters, containing the definition of the event information that will be delivered to the callback URL. The definition of this field is identical to the normal parameters field definition.

Example

We have chosen to use Github as our example, since it has a well formed subscription API.

Please refer to the Github documentation on 'create a hook'
for further information on the API definition provided by Github for webhooks.

Please note that all elements beginning with x-github or x-hub are part of the Github API
specification, and do not form part of this proposal.
Finally, the Swagger below is not comprehensive - for example, not all objects are fully modeled.

paths:
  /repos/owner/repo/hooks:
    post:
      operationId: 'CreateHook'
      summary: Create a webhook in GITHUB
      description: |
        Call this API to create a new WebHook in Github
      parameters:
        - name: subscription
          in: body
          description: Details to subscribe for a callback on a given set of events
          required: true
          schema:
            $ref: '#/definitions/Subscription'
      tags:
        - Webhook
      responses:
        '202':
          description: Details of the subscription created to the webhook
          schema:
            $ref: '#/definitions/SubscriptionResponse'
      x-event-streams:
        - eventId: commentStream
          description: Comment event stream
          parameters:
            - name: comment
              in: body
              required: true
              schema:
                $ref: '#/definitions/comment'
            - name: X-GitHub-Event
              in: header
              type: string
            - name: X-GitHub-Delivery
              in: header
              type: string
            - name: X-Hub-Signature
              in: header
              type: string

[fehguy]

Thanks @RobPhippen. A couple thoughts:

1. If we make this a formal part of the spec, we would remove the x- prefix. Is there a reason why it wouldn't be called webhookCallback? Or can this be used in a more general manner?
2. If the eventId is unique, I suggest we move it out of an array, and into a hash with the name of the eventId as the key
3. It looks like the definition in the eventId is effectively an Operation Object. This would help with code generation, schema design, etc.

[fehguy]

@casualjim I know you looked into this previously, any thoughts on the proposal?

[ePaul]

I'm missing any indication how the actual callback URL is passed (or rather, which of the properties in the Subscription object is the callback URL).

[RobPhippen]

Hi @ePaul that's absolutely right - that would require either standardisation of the subscription API, or semantic tagging of the 'real world' subscription API.

[RobPhippen]

It was proposed that standalone callbacks could go into the 'components' section, see #560

[fehguy]

Closing as #763 has been merged.