Overview

Metriport’s Real-time Patient Notifications are your way to receive real-time updates on a patient’s journey through a health system. You can trigger a workflow once a patient is admitted to a health system, check their diagnosis within moments of them being discharged, and so much more.

Working with Real-time Patient Notifications

Webhook schema (Event Reference)

Each real-time notification we send via webhook has a payload that includes key information about the event and a url field to a patient notification bundle containing the FHIR data relevant to that notification. The exact payload shape and bundle contents vary by event type. For ADT events, the url points to a Patient Encounter Bundle.

{
  "meta": {
    "messageId": "00000000-0000-0000-0000-000000000000",
    "requestId": "11111111-1111-1111-1111-111111111111",
    "when": "2025-01-30T23:00:01.000Z",
    "type": "patient.admit",
    "data": {
      "cxCan": "putAny",
      "stringKeyValue": "pairsHere"
    }
  },
  "payload": {
    "url": "<presigned-download-url>",
    "patientId": "metriport-patient-uuid",
    "externalId": "your-first-party-id",
    "whenSourceSent": "2025-01-30T22:58:45.000Z",
    "additionalIds": {
      "athenahealth": ["00000"]
    },
    "admitTimestamp": "2025-01-28T23:00:00.000Z"
  }
}

If you want to access the clinical data, download the bundle from the url. For ADT events, we recommend understanding The ADT Encounter Model below before working with the Patient Encounter Bundle.

The URL remains valid and available for download for 600 seconds (10 minutes).

The ADT Encounter Model

For ADT notifications, Metriport maintains the real-time state of a patient’s journey through the health system. Each of these patient journeys is represented via FHIR data through an Encounter.

{
  "resourceType": "Encounter",
  "status": "finished",
  "period": {
    "start": "2024-03-15T14:20:00.000Z",
    "end": "2024-03-15T16:45:00.000Z"
  },
  "reasonCode": [
    {
      "text": "Chest pain"
    }
  ],
  "location": [
    {
      "location": {
        "reference": "Location/3ca5e8d2-7c84-45ab-91e7-834f8becde12",
        "type": "Location",
        "display": "Memorial Hospital"
      }
    }
  ]
  // And much more
}

But FHIR data relies on references to function. An Encounter might reference a subject, a practitioner, or a location - as the example above does (see the reference field in location.). Each root unit of data in FHIR is called a ‘Resource’ and each of type of resource has its own corresponding schema. It’s common for resources to include references to one another. To provide comprehensive data about the Encounter for ADT events, we serve a Patient Encounter Bundle (a FHIR Bundle) via the url in the patient notification.

{
    "resourceType": "Bundle",
    "type": "message",
    "timestamp": "2020-05-08T13:10:15Z",
    "id": "message-uuid",
    "entry": [
      { /* the FHIR Patient */ },
      { /* a FHIR Encounter */ },
      // Other resources that are directly or transitively referenced via the FHIR encounter
      { /* Another resource */ },
      { /* Another resource */ },
      { /* Another resource */ },
      ...
    ]
}

For ADT notifications, the first two items in the bundle are the applicable patient and root Encounter. Every item thereafter is a resource referenced by the Encounter. If you’re unfamiliar with FHIR, read our FHIR Overview.

Handling Patient Notifications

We may extend the patient notification types, so we recommend that you do a strict match when checking the handler type. If using a typed language like typescript, this also allows you to typecast the payload based on the appropriate event type. See below.

import {
  PatientAdmitPayload,
  PatientDischargePayload,
} from "@metriport/api-sdk";

if (event.meta.type === "patient.admit") {
  const payload = event.payload as PatientAdmitPayload;
  // process admit message
}
if (event.meta.type === "patient.transfer") {
  const payload = event.payload as PatientTransferPayload;
  // process transfer message
}
if (event.meta.type === "patient.discharge") {
  const payload = event.payload as PatientDischargePayload;
  // process discharge message
}

How to enable real-time notifications

You can enable real-time notifications for the following sources:

ADTs: admission, discharge, and transfer notifications (and more) as patients move through healthcare facilities.

New updates to subscribe or remove patients from ADTs are only processed once a week, on Saturdays.

Pharmacies: notifications when patients get new prescriptions, pickup medications, and more.
Laboratories: notifications for new patient lab results.

Set up one or more Cohorts and associate the patients you want to have notifications enabled to the Cohorts.

Event Reference

`patient.laboratory`

A Patient Laboratory event indicates that a new laboratory notification is available for a patient.

Schema

meta

required

Metadata about the message.

Show meta properties

type

string

required

The type of the patient webhook data message. For a laboratory notification, it will be patient.laboratory.

payload

required

Show payload properties

url

string

required

The URL to download the patient notification bundle containing the FHIR data representing the comprehensive notification. It’s valid for 10 minutes.

specimenCollectedDate

string

When the lab specimen was collected for this notification.

Example payload

{
  "meta": {
    "messageId": "00000000-0000-0000-0000-000000000000",
    "requestId": "11111111-1111-1111-1111-111111111111",
    "when": "2026-03-26T18:00:00.000Z",
    "type": "patient.laboratory",
    "data": {
      "cxCan": "putAny",
      "stringKeyValue": "pairsHere"
    }
  },
  "payload": {
    "url": "<presigned-download-url>",
    "patientId": "metriport-patient-uuid",
    "externalId": "your-first-party-id",
    "additionalIds": {
      "athenahealth": ["00000"]
    },
    "specimenCollectedDate": "2026-03-26T18:00:00.000Z"
  }
}

`patient.pharmacy`

A Patient Pharmacy event indicates that a new pharmacy notification is available for a patient.

Schema

meta

required

Metadata about the message.

Show meta properties

type

string

required

The type of the patient webhook data message. For a pharmacy notification, it will be patient.pharmacy.

payload

required

Show payload properties

url

string

required

The URL to download the patient notification bundle containing the FHIR data representing the comprehensive notification. It’s valid for 10 minutes.

medicationDispensedDate

string

When the medication in this notification was dispensed.

Example payload

{
  "meta": {
    "messageId": "00000000-0000-0000-0000-000000000000",
    "requestId": "11111111-1111-1111-1111-111111111111",
    "when": "2026-03-26T18:00:00.000Z",
    "type": "patient.pharmacy",
    "data": {
      "cxCan": "putAny",
      "stringKeyValue": "pairsHere"
    }
  },
  "payload": {
    "url": "<presigned-download-url>",
    "patientId": "metriport-patient-uuid",
    "externalId": "your-first-party-id",
    "additionalIds": {
      "athenahealth": ["00000"]
    },
    "medicationDispensedDate": "2026-03-26T18:00:00.000Z"
  }
}

`patient.admit`

A Patient Admit event is emitted when a patient undergoes the admission process, assigning them a bed. It signals the official start of a patient’s stay in a healthcare facility. It includes short stay and “John Doe” (patient name unknown) admissions.

Schema

meta

required

Metadata about the message.

Show meta properties

type

string

required

The type of the patient webhook data message. For an admit, it will be patient.admit.

payload

PatientAdmitPayload

required

Show payload properties

url

string

required

The URL to download the Patient Encounter Bundle containing the FHIR data representing the comprehensive encounter. It’s valid for 10 minutes.

whenSourceSent

string

required

Specifies when this data was initially shared with Metriport.

admitTimestamp

string

When the patient for this encounter was officially admitted for care.

Example payload

{
  "meta": {
    "messageId": "00000000-0000-0000-0000-000000000000",
    "requestId": "11111111-1111-1111-1111-111111111111",
    "when": "2025-01-30T23:00:01.000Z",
    "type": "patient.admit"
  },
  "payload": {
    "url": "<presigned-download-url>",
    "patientId": "metriport-patient-uuid",
    "externalId": "your-first-party-id",
    "whenSourceSent": "2025-01-30T22:58:45.000Z",
    "additionalIds": {
      "athenahealth": ["00000"]
    },
    "admitTimestamp": "2025-01-28T23:00:00.000Z"
  }
}

`patient.transfer`

A Patient Transfer event indicates that a patient has been moved from one location to another within a healthcare system. This could represent a transfer between departments, units, or facilities.

Schema

meta

required

Metadata about the message.

Show meta properties

type

string

required

The type of the patient webhook data message. For a transfer, it will be patient.transfer.

payload

PatientTransferPayload

required

Show payload properties

url

string

required

The URL to download the Patient Encounter Bundle containing the FHIR data representing the comprehensive encounter. It’s valid for 10 minutes.

whenSourceSent

string

required

Specifies when this data was initially shared with Metriport.

admitTimestamp

string

When the patient for this encounter was officially admitted for care.

transfers

array

required

An array of transfer records, each representing a single transfer of the patient from one location to another.

Show array item properties

timestamp

string

When this specific transfer occurred.

sourceLocation

object

Information about the location the patient was transferred from.

Show object properties

name

string

The name of the source location.

type

string

The type of the source location (e.g., department, unit, facility).

destinationLocation

object

Information about the location the patient was transferred to.

Show object properties

name

string

The name of the destination location.

type

string

The type of the destination location (e.g., department, unit, facility).

Example payload

{
  "meta": {
    "messageId": "00000000-0000-0000-0000-000000000000",
    "requestId": "11111111-1111-1111-1111-111111111111",
    "when": "2025-01-30T20:30:01.000Z",
    "type": "patient.transfer",
    "data": {
      "cxCan": "putAny",
      "stringKeyValue": "pairsHere"
    }
  },
  "payload": {
    "url": "<presigned-download-url>",
    "patientId": "metriport-patient-uuid",
    "externalId": "your-first-party-id",
    "whenSourceSent": "2025-01-30T20:28:30.000Z",
    "additionalIds": {
      "athenahealth": ["00000"]
    },
    "admitTimestamp": "2025-01-28T23:00:00.000Z",
    "transfers": [
      {
        "timestamp": "2025-01-29T15:45:00.000Z",
        "sourceLocation": {
          "name": "Emergency Department",
          "type": "department"
        },
        "destinationLocation": {
          "name": "General Medical Ward",
          "type": "unit"
        }
      },
      {
        "timestamp": "2025-01-30T20:30:00.000Z",
        "sourceLocation": {
          "name": "General Medical Ward",
          "type": "unit"
        },
        "destinationLocation": {
          "name": "Intensive Care Unit",
          "type": "unit"
        }
      }
    ]
  }
}

`patient.discharge`

A Patient Discharge event indicates the end of a patient’s stay in a healthcare facility. The patient now has the status “discharged” and an officially recorded discharge date.

Schema

meta

required

Metadata about the message.

Show meta properties

type

string

required

The type of the patient webhook data message. For a discharge, it will be patient.discharge.

payload

PatientDischargePayload

required

Show payload properties

url

string

required

The URL to download the Patient Encounter Bundle containing the FHIR data representing the comprehensive encounter. It’s valid for 10 minutes.

whenSourceSent

string

required

Specifies when this data was initially shared with Metriport.

admitTimestamp

string

When the patient for this encounter was officially admitted for care.

dischargeTimestamp

string

When the patient for this encounter was officially discharged by the provider.

Example payload

{
  "meta": {
    "messageId": "00000000-0000-0000-0000-000000000000",
    "requestId": "11111111-1111-1111-1111-111111111111",
    "when": "2025-01-30T23:00:01.000Z",
    "type": "patient.discharge",
    "data": {
      "cxCan": "putAny",
      "stringKeyValue": "pairsHere"
    }
  },
  "payload": {
    "url": "<presigned-download-url>",
    "patientId": "metriport-patient-uuid",
    "externalId": "your-first-party-id",
    "whenSourceSent": "2025-01-30T22:58:45.000Z",
    "additionalIds": {
      "athenahealth": ["00000"]
    },
    "admitTimestamp": "2025-01-28T23:00:00.000Z",
    "dischargeTimestamp": "2025-01-30T23:00:00.000Z"
  }
}

Additional Resources

FHIR Encounter

For ADT notifications, the Encounter is the core resource in a Patient Encounter Bundle. Below is an example of a FHIR Encounter resource, which is one piece of the data you’ll receive when downloading the bundle from the notification url.

Getting Started

API Reference

Handling Data

FHIR

API Tools

More Info

Legacy API Reference

Real-time Patient Notifications

Overview

Working with Real-time Patient Notifications

Webhook schema (Event Reference)

The ADT Encounter Model

Handling Patient Notifications

How to enable real-time notifications

Event Reference

`patient.laboratory`

Schema

Example payload

`patient.pharmacy`

Schema

Example payload

`patient.admit`

Schema

Example payload

`patient.transfer`

Schema

Example payload

`patient.discharge`

Schema

Example payload

Additional Resources

FHIR Encounter

​Overview

​Working with Real-time Patient Notifications

​Webhook schema (Event Reference)

​The ADT Encounter Model

​Handling Patient Notifications

​How to enable real-time notifications

​Event Reference

​patient.laboratory

​Schema

​Example payload

​patient.pharmacy

​Schema

​Example payload

​patient.admit

​Schema

​Example payload

​patient.transfer

​Schema

​Example payload

​patient.discharge

​Schema

​Example payload

​Additional Resources

​FHIR Encounter

Overview

Working with Real-time Patient Notifications

Webhook schema (Event Reference)

The ADT Encounter Model

Handling Patient Notifications

How to enable real-time notifications

Event Reference

`patient.laboratory`

Schema

Example payload

`patient.pharmacy`

Schema

Example payload

`patient.admit`

Schema

Example payload

`patient.transfer`

Schema

Example payload

`patient.discharge`

Schema

Example payload

Additional Resources

FHIR Encounter