April 14, 2026: Patient UPID now included in all Zushook payloads

Zushook webhook payloads now include a top-level upid field containing the patient's Universal Patient ID (UPID) whenever one is extractable from the resource. This field is present for all authentication types — OAuth, basic, and unauthenticated — and regardless of whether the full FHIR resource is included in the payload.

Why this matters Previously, when a resource exceeded the 1 MB size limit, OAuth-authenticated Zushooks set resourceIncluded to false and resource to null, with no way to identify the associated patient. Consumers had to make additional API calls to determine which patient the webhook pertained to. The new upid field ensures the patient identity is always available.

Example payload (resource exceeds size limit)

{
    "message_id": "123",
    "source": "com.zushealth.zushooks",
    "time": "2026-04-15T13:48:32Z",
    "resourceId": "Binary/c020d8eb-ea59-492b-862f-c27f9556f628",
    "ownerId": "builder/abc",
    "resourceIncluded": false,
    "upid": "75bf769f-d309-4243-a98d-0d12e339b468",
    "resource": null,
    "operationType": "UPSERT"
}

Deprecation notice For basic and unauthenticated Zushooks, the patient UPID was previously embedded in the resource field as resource.UPID when the full resource was not included. This behavior is preserved for backwards compatibility but is deprecated. Consumers should migrate to reading the top-level upid field instead.

This applies to all Zushook messages delivered on or after April 15, 2026.