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.
| Type | Project feature |
Value in features | websocket-subscriptions |
| Change with | PATCH /v1/projects/me/features (replaces the whole list) |
| Who can change it | Project admin. Any practitioner can read the list. |
| On for new projects | Yes |
| Not needed for | Subscriptions that use a rest-hook channel or deliver to a Bot |
| When off | Requesting 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:
| Socket | wss://api.sandbox.ovok.com/ws/subscriptions-r4 |
| Binding token | GET 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
| Limit | What happens |
|---|---|
| No traffic either way for 60 seconds | The 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 address | Further upgrades answer 429 until some close. Clients behind one NAT share the limit. |
What it gates
| Capability | Behaviour when the feature is off |
|---|---|
GET /fhir/R4/Subscription/:id/$get-ws-binding-token | 400 with WebSocket subscriptions not enabled for current project |
| Delivery of notifications to a WebSocket channel | Not delivered |
Subscriptions with a rest-hook channel | Unaffected |
| Subscriptions that deliver to a Bot | Unaffected, 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-hookwhen 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/featuresand check.
Related
Last updated on