Features

websocket-subscriptions

Receive live updates over a WebSocket Subscription channel, what the feature gates, and what it does not.

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 API host, the same host as every other Ovok call. In the sandbox:

Socketwss://api.sandbox.ovok.com/ws/subscriptions-r4
Binding tokenGET https://api.sandbox.ovok.com/fhir/R4/Subscription/:id/$get-ws-binding-token. Its websocket-url parameter names the socket above.

Use the socket path exactly as given: an upgrade with a query string or a trailing slash is refused. A client built on @medplum/core (MedplumClient.subscribeToCriteria) with the API host as its base URL connects there on its own.

Limits

LimitWhat happens
No traffic either way for 60 secondsThe connection is dropped (close code 1006). A bound socket receives a heartbeat every 10 seconds, so only a socket that never binds, or is abandoned, reaches this.
Too many open sockets from one client addressFurther upgrades answer 429 until some close. Clients behind one NAT share the limit.

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 API host. Earlier versions of this page sent WebSocket clients to the FHIR store's own host. Move them to the API host.
  • 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.

Last updated on

On this page