Skip to main content

websocket-subscriptions

Lets the project use Subscriptions that deliver notifications over a WebSocket, so an app can react to data changes without polling.

TypeProject feature
Value in featureswebsocket-subscriptions
Change withPATCH /v1/projects/me/features (replaces the whole list)
Who can change itProject admin. Any practitioner can read the list.
On for new projectsYes
Not needed forSubscriptions that use a rest-hook channel or deliver to a Bot
When offRequesting a WebSocket binding token is refused, and WebSocket Subscriptions are not delivered

This page covers the project switch and where the WebSocket connection is served. It does not describe the messages a client sends after it connects.

Where the WebSocket connection is served​

WebSocket connections go to the FHIR host, not the API host. In the sandbox:

Host/ws/subscriptions-r4
fhir.sandbox.ovok.comAccepts the WebSocket upgrade (101 Switching Protocols).
api.sandbox.ovok.comDoes not carry WebSocket traffic. The upgrade fails with 502.

The HTTP operation that issues the binding token is available on both hosts, so you can request a token from either and then connect to the FHIR host. Use the FHIR host for your environment; it is not the same as the API host.

What it gates​

CapabilityBehaviour when the feature is off
GET /fhir/R4/Subscription/:id/$get-ws-binding-token400 with WebSocket subscriptions not enabled for current project
Delivery of notifications to a WebSocket channelNot delivered
Subscriptions with a rest-hook channelUnaffected
Subscriptions that deliver to a BotUnaffected, but need bots

Turn it on​

curl --request PATCH \
  --url 'https://api.sandbox.ovok.com/v1/projects/me/features' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"features":["bots","cron","email","transaction-bundles","websocket-subscriptions"]}'

Request a binding token for a Subscription you have created:

curl --get "https://api.sandbox.ovok.com/fhir/R4/Subscription/${SUBSCRIPTION_ID}/\$get-ws-binding-token" \
  --header "Authorization: Bearer ${OVOK_TOKEN}"

The Subscription must exist and be readable by the caller. For an id that does not exist the request answers 400 with Error reading subscription: Not found.

Gotchas​

  • The feature is checked on the project the data belongs to. In a project hierarchy, enable it on each project whose Subscriptions you expect to be delivered.
  • Turning it off stops delivery without deleting the Subscription. The resource stays; nothing is sent until you turn the feature back on.
  • A token is not a subscription. The binding token is tied to the Subscription it was issued for and the identity that asked for it.
  • Connect to the FHIR host, not the API host. A client that opens its WebSocket against the API host gets 502.
  • Prefer rest-hook when a server is the receiver. WebSocket delivery suits apps that stay open; a back end is better served by a webhook or a Bot.
  • Projects created before this was a default can lack it. Call GET /v1/projects/me/features and check.