Patient Activity Notifications

1. Overview

Patient activity subscriptions notify your application when new data is added to a patient record visible to your builder. Instead of sending a webhook for every new resource, Zus sends one notification per patient per configured interval. Use the patient's Universal Patient Identifier (UPID) from the notification to run an incremental Group $export.

Key behavior

• One notification per patient per interval. The interval starts when the first new resource arrives. Additional writes during that interval do not reset the timer.
• Any write counts. New or updated Conditions, Observations, documents, Encounters, medications, and other resources that carry the patient's UPID trigger a notification. Resources without a UPID, such as Practitioners and Organizations, do not.
• No resource filters. Filters are not currently supported for this subscription type.
• No clinical data in the webhook. The payload contains only the patient's upid and group reference.
• Not a FHIR Subscription resource. Zus configures and manages patient activity subscriptions separately from FHIR Subscription resources.

Choosing a subscription type

Notification flow

1. A resource for the patient is written in Zus.
2. If no interval is open for that patient and subscription, Zus starts one.
3. When the interval ends, Zus sends a POST to your webhook.
4. Your application runs $export using the patient's saved _since bookmark.
5. After a successful export, your application saves the manifest's transactionTime as the patient's next _since bookmark. See Sync with $export.

2. Prerequisites

Hosts

Use your app client's credentials to get an access token from the token endpoint, and send it as Authorization: Bearer <token> on $export requests. You do not need access to the subscriptions API.

3. Request a subscription

Zus sets up subscriptions on request. Contact your Zus account manager and provide the following for each environment. Zus confirms when the subscription is active.

4. Receive and verify notifications

Zus sends a POST to your webhook for each patient with activity during the interval.

POST https://webhooks.example.com/zus/patient-activity
Content-Type: application/json
Authorization: Basic <base64(username:password)>

{
  "upid": "c4b1d2e9-6bb4-4df5-b5c2-7b4761ace72e",
  "group": "Group/c4b1d2e9-6bb4-4df5-b5c2-7b4761ace72e"
}

With OAuth 2.0, the header is Authorization: Bearer <token>. The body is the same for both methods.

Ignore any unrecognized fields so your handler stays compatible with future additions.

Verify that the call came from Zus

Notifications are not signed. Verify the Authorization header on every request.

Return 401 for invalid credentials. Zus retries a 401 like any other non-2xx response.

Treat webhook input as untrusted. Validate that upid is a UUID before using it in an export URL, and authenticate the request before scheduling any work.

Timing

• The alert is sent within about a minute of the interval closing. The interval starts at the first new resource for the patient, not the last.
• There is no alert for a patient with no new data.

Rotate webhook credentials

Contact Zus and provide the replacement credentials over a secure channel. Zus confirms when the new credentials are active. Until then, and for a short time afterward, accept both the old and new credentials so in-flight and retried requests can complete.

5. Process notifications and sync with $export

Recommended handler

1. Verify the Authorization header. Return 401 on failure.
2. Parse the body and validate that upid is a UUID. Return 400 on failure.
3. Enqueue an export for upid. If an export for that UPID is already queued or running, do not schedule a duplicate.
4. Return 200 or 202 once the work is queued, well within the 120 second timeout. Zus ignores the response body.

Do not wait for $export to finish before responding.

Delivery semantics

Sync with $export

For each notification, run POST /Group/{upid}/$export?_since=<bookmark> against the export host. See Bulk FHIR Export for parameters, polling, and downloading.

• Keep a per-patient _since bookmark, independent of notifications. The notification has no change timestamp, and a notification can be delayed or retried.
• Update the bookmark only after a successful export.
• Save the manifest's transactionTime as the next bookmark, and send it as _since on the patient's next export. Do not use the time you started the export job.
• Resources written in the 15 minutes before an export request are always included, so consecutive incremental exports overlap. Upsert by resource ID.
• On 409 Conflict, an export is already running for this patient and builder. Continue with the job in the Content-Location header.

6. What exports will not show

A notification can arrive for a change that the export does not contain:

• Restricted-access data. A resource with a specially regulated security label triggers a notification but is withheld from the export.
• Binary resources. The export never emits Binary resources. Document content is delivered through DocumentReference.

A notification with no new export data can also be a duplicate that arrived after an earlier export already picked up the change.

7. Change or remove a subscription

Contact your Zus account manager with the environment, builder, subscription name, and the requested change. Share any new webhook credentials over an approved secure channel.

• Interval changes apply to notification windows opened after the update. Windows already in progress keep the previous interval.
• suppressOwnWrites changes apply to subsequent writes.
• Webhook URL and credential changes take effect shortly after Zus applies them, including for retries. Zus confirms when the change is active.
• Removal. Zus confirms when the subscription is removed. Notifications that were already pending may still arrive for a short time afterward.

8. Test in sandbox and go live

Sandbox test procedure

1. Get a sandbox token with your sandbox app client. The audience is https://api.sandbox.zusapi.com.
2. Send Zus the sandbox configuration from Request a subscription, with an interval of 30m and your sandbox webhook URL. Wait for Zus to confirm the subscription is active.
3. Pick a sandbox patient visible to your builder and note its UPID.
4. Write a resource for the patient through the sandbox FHIR API at https://api.sandbox.zusapi.com/fhir, for example POST /fhir/Observation. If suppressOwnWrites is true, your own writes will not trigger a notification. Coordinate with Zus to use a test configuration with that setting disabled, or ask Zus to load test data.
5. Allow about 31 minutes for the first notification. Write a second resource during the same interval and confirm you receive only one notification for the patient.
6. Run $export against https://fqs.sandbox.zusapi.com with _since set to a time before your writes, and confirm the new resources are in the output.
7. Return a 500 from your endpoint for one alert, and confirm that Zus retries the delivery.

If you need a connectivity or authentication check first, ask Zus to help validate webhook delivery. Test your payload parser with a real patient activity notification, since a generic test payload may have a different format.

Go-live checklist

• Production app client created and token flow working against https://auth.zusapi.com/oauth/token
• Production webhook reachable over HTTPS and accepting the credentials shared with Zus
• Handler verifies the Authorization header and validates the UPID
• Handler returns 2xx within a few seconds and queues the export asynchronously
• Export jobs coalesce by UPID, honor Retry-After, handle 409, and use per-patient bookmarks
• Alerting on a sustained rate of non-2xx responses, so an outage is fixed before notifications are paused
• Initial full export and per-patient bookmarks ready before Zus enables production notifications
• Zus has confirmed the production subscription is active with the requested interval and suppressOwnWrites setting

9. Limits and FAQ

Why did I get a notification but no new export data?

The change may have come from your own builder with suppressOwnWrites set to false. The resource may carry a specially regulated security label, which triggers a notification but is withheld from the export. Or the notification may be a duplicate that arrived after an export already processed the change.

Why didn't a patient with new data trigger a notification?

Check whether the patient is visible to your builder, whether suppressOwnWrites excluded the write, and whether the interval has ended. Repeated webhook failures can also pause a patient's notifications. Review your webhook logs and ask Zus to investigate if needed.

Can the webhook include the resource instead of requiring an export?

Not with patient activity subscriptions. For resource-level notifications, use a filtered resource subscription. Those send a notification per resource rather than once per patient per interval.

When does the interval start?

When the first qualifying resource is written. Additional resources during the interval do not extend it.

What happens when patient records are merged or split?

Notifications do not currently identify merges or splits, or map between UPIDs. After a merge, the resulting patient record may receive later notifications under its own UPID. A dedicated merge and split signal is on the roadmap.

Is this a FHIR Subscription resource?

No. Zus configures and manages patient activity subscriptions separately from FHIR Subscription resources. The webhook identifies the patient as Group/<upid> for use with $export.

Support

Contact your Zus account manager or [email protected] with the environment, subscription name, UPID, approximate notification time, and any relevant webhook response codes or error messages. Zus can investigate delivery attempts and resume paused notifications.

Related pages

• Bulk FHIR Export
• Creating App Clients
• Rate Limits