Specification: Ballerina WebSub Library

Owners: @shafreenAnfar @chamil321 @ayeshLK
Reviewers: @chamil321
Created: 2022/01/31
Updated: 2022/05/23
Edition: Swan Lake


This is the specification for the WebSub standard library of Ballerina language, which provides WebSub compliant subscriber related functionalities.

The WebSub library specification has evolved and may continue to evolve in the future. The released versions of the specification can be found under the relevant Github tag.

If you have any feedback or suggestions about the library, start a discussion via a GitHub issue or in the Slack channel. Based on the outcome of the discussion, the specification and implementation can be updated. Community feedback is always welcome. Any accepted proposal which affects the specification is stored under /docs/proposals. Proposals under discussion can be found with the label type/proposal in Github.

The conforming implementation of the specification is released and included in the distribution. Any deviation from the specification is considered a bug.


  1. Overview
  2. Subscriber

1. Overview

WebSub is a real-time content delivery protocol over HTTP(S) and it is a specification which evolved from PubSubHubbub.

WebSub specification describes three main roles:

  • Publisher: Advertises a topic and hub URL on one or more resource URLs.
  • Subscriber: Discovers the hub and topic URL given a resource URL, subscribes to updates at the hub, and accepts content distribution requests from the hub.
  • Hub: Handles subscription requests and distributes the content to subscribers when the corresponding topic URL has been updated.

WebSub is a library which is derived from the WebSub specification which could be used by developers to implement WebSub compliant subscriber services.

2. Subscriber

WebSub subscriber will subscribe to a hub to receive content updates for a topic.

It has the following capabilities:

  • Discover the hub and the topic given a resource URL
  • Subscribe to content updates for a topic in a hub
  • Accept content distribution requests from the hub

The subscriber is designed in the form of listener and Subscriber Service.

  • websub:Listener: A listener end-point to which websub:SubscriberService could be attached.
  • websub:SubscriberService: An API service, which receives events.

2.1. Listener

The websub:Listener opens the given port and attaches the provided websub:SubscriberService object to the given service-path. websub:Listener can be initialized either by providing a port with listener configurations or by providing an http:Listener.

2.1.1. Configuration

When initializing a websub:Listener, following configurations could be provided.

For more details on the available configurations please refer http:ListenerConfiguration.

2.1.2. Initialization

The websub:Listener could be initialized by providing either a port with websub:ListenerConfiguration or by providing an http:Listener.

2.1.3. Methods

Following APIs should be available in the websub:Listener to dynamically attach websub:SubscriberService objects to it.

Following APIs should be available in the websub:Listener to dynamically attach websub:SubscriberService objects along with websub:SubscriberServiceConfiguration. This is useful when the subscriber is implemented using a service class.

Following APIs should be available in the websub:Listener to dynamically detach websub:SubscriberService objects from it.

Following APIs should be available to dynamically start the websub:Listener.

Following APIs should be available to dynamically stop the websub:Listener.

2.2. Subscriber Service

websub:SubscriberService is responsible for handling the received events. Underlying http:Service will receive the original request, and then it will trigger the WebSub dispatcher which will invoke the respective remote method with the event details.

Following is the type-definition for websub:SubscriberService.

2.2.1. Methods onSubscriptionValidationDenied

This remote method is invoked when the hub sends a request to notify that the subscription request is denied. onSubscriptionVerification

This remote method is invoked when the hub sends a subscription verification request to the subscriber. onUnsubscriptionVerification

This remote method is invoked when the hub sends a unsubscription verification request to the subscriber. onEventNotification

This remote method is invoked when the hub sends a content-distribution request to the subscriber.

2.2.2. Annotation

Apart from the listener level configurations a subscriber will require few additional configurations. Hence, there should be websub:SubscriberServiceConfig a service-level-annotation for websub:SubscriberService which contains websub:SubscriberServiceConfiguration record.

2.2.3. Callback URL Generation

As per the WebSub specification subscriber callback URL could be used as an identity of a subscriber at the hub level, and it should be unguessable and unique for a subscription.

Since the developer should have the control over the callback URL to be used when subscribing to a hub, websub:SubscriberServiceConfig annotation contains an optional configuration(callback) to be used to provide a callback URL. If the callback is not configured, websub:SubscriberService should be able to construct the callback URL using the provided websub:ListenerConfiguration and service path. Service Path Generation

In ballerina service declaration, service path is an optional configuration. Hence, developers could declare websub:SubscriberService by omitting the service path. Since, service path is required for constructing the callback URL, websub:SubscriberService should be able to generate a unique, unguessable URL segment to be used as its service path.

Service path generation should be implemented with following guidelines:

  • Service path should be generated only if;
    • Service path and callback URL is not provided for the websub:SubscriberService.
    • callback URL is provided, appendServicePath configuration is enabled and service path is not provided.
  • WebSub compiler plugin will generate unique service path for the websub:SubscriberService and populate servicePath field in websub:SubscriberServiceConfig annotation.
  • If there is an error while generating the service path, then it should result in a compile-time error since this feature is required to generate a callback URL and without it subscriber service could not be used.
  • If the callback URL is provided without the service path then the websub:SubscriberService will be attached to the default service path which is /.

2.2.4. Unsubscribing from the hub

As per the WebSub Specification a subscriber should be able to subscribe to a particular topic in a specific hub. As the counterpart subscriber should be able to unsubscribe from a previously subscribed topic in a specific hub. Even though the specification does not clearly define when this unsubscription should happen, it is obvious that this should happen whenever subscriber is terminated.

The key functionalities expected from the unsubscription flow as follows:

  • Developer should manually enable this feature by configuring unsubscribeOnShutdown in websub:SubscriberServiceConfig annotation.
  • Developer should be able to configure unsubscription verification time-out using gracefulShutdownPeriod configuration in websub:ListenerConfiguration.
  • Unsubscription flow should be initiated whenever the graceful stop is invoked in websub:Listener.
  • If multiple websub:SubscriberService instances are attached to one websub:Listener, all the subscriber instances which have enabled unsubscribeOnShutdown should initiate unsubscription on listener shutdown.
  • Unsubscription flow should be initiated only if graceful stop is invoked, and will not be executed for immediate stop .