# websocket-subscriptions

Canonical page: https://docs.ovok.com/settings-and-features/features/websocket-subscriptions

Lets the project use [Subscriptions](/api/fhir/r4/subscription) 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 [#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 [#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 [#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](/settings-and-features/features/bots) |

## Turn it on [#turn-it-on]

```bash
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:

```bash
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 [#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.

## Related [#related]

- [Subscription](/api/fhir/r4/subscription)
- [bots](/settings-and-features/features/bots)
- [Listening for changes](/fhir-basics#listening-for-changes-subscriptions)
