WebSocket integration

The WebSocket integration allows consuming device events using a simple WebSockets based protocol. Events are encoded as CloudEvents.

The application you want to consume must be passed as a path parameter. As an example, here is the url to connect to if you want to stream events for the application example-app :

wss://ws-integration.sandbox.drogue.cloud/example-app

Authentication

The Websocket endpoint allows you to authenticate using the standard HTTP Authorization header. Both using an OAuth2 bearer token or by using HTTP "basic auth" using username and API key.

However, when using a web socket client from inside a browser, that is not supported. In this case it is however possible to provide the same information using HTTP query parameters:

Query Parameters Description

Query Parameters	Description
`token`	Provide an OAuth2 bearer token
`username` and `api_key`	Provide username and API key

token

Provide an OAuth2 bearer token

username and api_key

Provide username and API key

Refreshing the Oauth2 token

Oauth bearer tokens usually have a short lifespan. When the token is expired, the Websocket endpoint will close the connexion. To keep the connexion alive, you can refresh the token by sending a json payload through the web socket containing a refreshed token. The bearer token must be passed with a key named RefreshAccessToken.

Here is an example:

{
   "RefreshAccessToken":"eyJhbGciO[...]sRqg7xt_jzb_tg"
}

Channel filter

You can set an additional path segment after the application ID to select a specific channel you want to consume the events from.

For example, if you want to consume events only from the sensor channel you would connect to :

wss://ws-integration.sandbox.drogue.cloud/example-app/sensor

Consumer Group ID

You can set the consumer group ID by providing a query parameter named group_id. This will set the Kafka consumer group ID to the provided value, allowing to share the load between different consumers.

If no consumer group id is provided, a temporary one will be provided.

Using a temporary consumer group might lead to missed events during re-connects. If that is a problem for your use case, you need to provide a stable group id.