Actions

The ballerina/websub package exposes the following clients:

Client	Purpose
Subscription Client	Sends subscription and unsubscription requests to a WebSub hub.
Discovery Service	Discovers WebSub hub and topic URLs from a resource URL via HTTP Link headers.

For event-driven integration, see the Trigger Reference.

---

Subscription client

Sends subscription and unsubscription requests to a WebSub hub.

Configuration

Field	Type	Default	Description
httpVersion	http:HttpVersion	HTTP_2_0	HTTP protocol version to use.
http1Settings	http:ClientHttp1Settings	{}	HTTP/1.x specific settings.
http2Settings	http:ClientHttp2Settings	{}	HTTP/2 specific settings.
timeout	decimal	60	Maximum wait time for a response in seconds.
followRedirects	http:FollowRedirects	()	Redirect handling configuration.
poolConfig	http:PoolConfiguration	()	Connection pooling configuration.
auth	http:ClientAuthConfig	()	Client authentication configuration.
retryConfig	http:RetryConfig	()	Retry configuration for failed requests.
responseLimits	http:ResponseLimitConfigs	{}	Response size limit configuration.
secureSocket	http:ClientSecureSocket	()	SSL/TLS configuration.
circuitBreaker	http:CircuitBreakerConfig	()	Circuit breaker configuration for fault tolerance.

Initializing the client

import ballerina/websub;

configurable string hubUrl = ?;

websub:SubscriptionClient subscriptionClient = check new (hubUrl);

Operations

Subscription management

subscribe

Sends a subscription request to the WebSub hub for the specified topic.

Parameters:

Name	Type	Required	Description
subscriptionRequest	SubscriptionChangeRequest	Yes	The subscription request containing the topic URL, callback URL, and optional parameters such as secret and leaseSeconds.

Returns: SubscriptionChangeResponse|SubscriptionInitiationError

Sample code:

websub:SubscriptionChangeResponse response = check subscriptionClient->subscribe({
    topic: "https://example.com/feed",
    callback: "https://my-app.example.com/websub"
});

Sample response:

{"hub": "https://hub.example.com", "topic": "https://example.com/feed", "response": "<http:Response>"}

unsubscribe

Sends an unsubscription request to the WebSub hub for the specified topic.

Parameters:

Name	Type	Required	Description
unsubscriptionRequest	SubscriptionChangeRequest	Yes	The unsubscription request containing the topic URL and callback URL.

Returns: SubscriptionChangeResponse|SubscriptionInitiationError

Sample code:

websub:SubscriptionChangeResponse response = check subscriptionClient->unsubscribe({
    topic: "https://example.com/feed",
    callback: "https://my-app.example.com/websub"
});

Sample response:

{"hub": "https://hub.example.com", "topic": "https://example.com/feed", "response": "<http:Response>"}

---

Discovery service

Discovers WebSub hub and topic URLs from a resource URL via HTTP Link headers.

Configuration

Field	Type	Default	Description
httpVersion	http:HttpVersion	HTTP_2_0	HTTP protocol version to use.
http1Settings	http:ClientHttp1Settings	{}	HTTP/1.x specific settings.
http2Settings	http:ClientHttp2Settings	{}	HTTP/2 specific settings.
timeout	decimal	60	Maximum wait time for a response in seconds.
followRedirects	http:FollowRedirects	()	Redirect handling configuration.
poolConfig	http:PoolConfiguration	()	Connection pooling configuration.
auth	http:ClientAuthConfig	()	Client authentication configuration.
retryConfig	http:RetryConfig	()	Retry configuration for failed requests.
responseLimits	http:ResponseLimitConfigs	{}	Response size limit configuration.
secureSocket	http:ClientSecureSocket	()	SSL/TLS configuration.
circuitBreaker	http:CircuitBreakerConfig	()	Circuit breaker configuration for fault tolerance.

Initializing the client

import ballerina/websub;

configurable string resourceUrl = ?;

websub:DiscoveryService discoveryClient = check new (resourceUrl);

Operations

Resource discovery

discoverResourceUrls

Discovers the WebSub hub URL and topic URL from the resource URL by parsing HTTP Link headers.

Parameters:

Name	Type	Required	Description
expectedMediaTypes	string?|string[]	No	Expected media types for the resource (used in the Accept header).
expectedLanguageTypes	string?|string[]	No	Expected language types for the resource (used in the Accept-Language header).

Returns: [string, string]|ResourceDiscoveryFailedError

Sample code:

[string hubUrl, string topicUrl] = check discoveryClient->discoverResourceUrls();

Sample response:

["https://hub.example.com", "https://example.com/feed"]