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. For discharge summaries, the url points to a FHIR collection Bundle of resources from the matching HIE discharge summary document.

{
  "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. For discharge summaries, download the FHIR collection from the url on patient.discharge-summary.

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,
  PatientPreAdmitPayload,
  PatientRegisterPayload,
  PatientTransferPayload,
  PatientVisitUpdatePayload,
} from "@metriport/api-sdk";

if (event.meta.type === "patient.pre-admit") {
  const payload = event.payload as PatientPreAdmitPayload;
  // process pre-admit message
}
if (event.meta.type === "patient.register") {
  const payload = event.payload as PatientRegisterPayload;
  // process registration message
}
if (event.meta.type === "patient.admit") {
  const payload = event.payload as PatientAdmitPayload;
  // process admit message
}
if (event.meta.type === "patient.visit-update") {
  const payload = event.payload as PatientVisitUpdatePayload;
  // process visit update 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

required

Metadata about the message.

Show meta properties

string

required

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

required

Show payload properties

string

required

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

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

required

Metadata about the message.

Show meta properties

string

required

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

required

Show payload properties

string

required

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

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.pre-admit`

A Patient Pre-admit event is emitted when a facility records a planned or pending admission, before the patient arrives.

Schema

required

Metadata about the message.

Show meta properties

string

required

The type of the patient webhook data message. For a pre-admit, it will be patient.pre-admit.

PatientPreAdmitPayload

required

Show payload properties

string

required

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

string

required

Specifies when this data was initially shared with Metriport.

string

When the facility recorded the pre-admission.

string

When the facility expects to admit the patient.

string

The encounter class the facility expects for the admission, such as emergency or inpatient encounter.

string

The reason given for the planned admission.

Example payload

{
  "meta": {
    "messageId": "00000000-0000-0000-0000-000000000000",
    "requestId": "11111111-1111-1111-1111-111111111111",
    "when": "2025-01-28T18:00:01.000Z",
    "type": "patient.pre-admit"
  },
  "payload": {
    "url": "<presigned-download-url>",
    "patientId": "metriport-patient-uuid",
    "externalId": "your-first-party-id",
    "whenSourceSent": "2025-01-28T17:58:45.000Z",
    "additionalIds": {
      "athenahealth": ["00000"]
    },
    "preAdmitTimestamp": "2025-01-28T18:00:00.000Z",
    "plannedAdmitTimestamp": "2025-01-29T14:00:00.000Z",
    "plannedClass": "inpatient encounter",
    "reason": "Chest pain"
  }
}

`patient.register`

A Patient Register event is emitted when a patient checks in at a facility, often before they are assigned a bed. Registration is not itself an inpatient admission.

Schema

required

Metadata about the message.

Show meta properties

string

required

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

PatientRegisterPayload

required

Show payload properties

string

required

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

string

required

Specifies when this data was initially shared with Metriport.

string

When the patient was registered for this visit.

string

The class of the visit at registration, such as emergency or inpatient encounter.

Example payload

{
  "meta": {
    "messageId": "00000000-0000-0000-0000-000000000000",
    "requestId": "11111111-1111-1111-1111-111111111111",
    "when": "2025-01-28T22:10:01.000Z",
    "type": "patient.register"
  },
  "payload": {
    "url": "<presigned-download-url>",
    "patientId": "metriport-patient-uuid",
    "externalId": "your-first-party-id",
    "whenSourceSent": "2025-01-28T22:08:45.000Z",
    "additionalIds": {
      "athenahealth": ["00000"]
    },
    "registerTimestamp": "2025-01-28T22:07:00.000Z",
    "encounterClass": "emergency"
  }
}

`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. The same event type is sent when a visit changes class, for example from emergency to inpatient. In that case the payload includes previousClass and, when the visit was registered earlier, registerTimestamp. An admission that is not a class change omits those two fields.

Schema

required

Metadata about the message.

Show meta properties

string

required

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

PatientAdmitPayload

required

Show payload properties

string

required

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

string

required

Specifies when this data was initially shared with Metriport.

string

When the patient for this encounter was officially admitted for care. On a class change, this is the time the class changed.

string

The encounter class before this event, such as emergency. Present only when this admit is a class change.

string

When the patient was registered for this visit. Present only when this admit is a class change and the visit was registered earlier.

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"
  }
}

Class change from emergency to inpatient:

{
  "meta": {
    "messageId": "00000000-0000-0000-0000-000000000000",
    "requestId": "11111111-1111-1111-1111-111111111111",
    "when": "2025-01-29T04:55:01.000Z",
    "type": "patient.admit"
  },
  "payload": {
    "url": "<presigned-download-url>",
    "patientId": "metriport-patient-uuid",
    "externalId": "your-first-party-id",
    "whenSourceSent": "2025-01-29T04:53:45.000Z",
    "additionalIds": {
      "athenahealth": ["00000"]
    },
    "admitTimestamp": "2025-01-29T04:55:13.000Z",
    "previousClass": "emergency",
    "registerTimestamp": "2025-01-28T23:07:00.000Z"
  }
}

`patient.visit-update`

A Patient Visit Update event is emitted when an existing visit receives new diagnosis information.

Schema

required

Metadata about the message.

Show meta properties

string

required

The type of the patient webhook data message. For a visit update, it will be patient.visit-update.

PatientVisitUpdatePayload

required

Show payload properties

string

required

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

string

required

Specifies when this data was initially shared with Metriport.

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-29T01:20:01.000Z",
    "type": "patient.visit-update"
  },
  "payload": {
    "url": "<presigned-download-url>",
    "patientId": "metriport-patient-uuid",
    "externalId": "your-first-party-id",
    "whenSourceSent": "2025-01-29T01:18: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

required

Metadata about the message.

Show meta properties

string

required

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

PatientTransferPayload

required

Show payload properties

string

required

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

string

required

Specifies when this data was initially shared with Metriport.

string

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

array

required

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

Show array item properties

string

When this specific transfer occurred.

object

Information about the location the patient was transferred from.

Show object properties

string

The name of the source location.

string

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

object

Information about the location the patient was transferred to.

Show object properties

string

The name of the destination location.

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

required

Metadata about the message.

Show meta properties

string

required

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

PatientDischargePayload

required

Show payload properties

string

required

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

string

required

Specifies when this data was initially shared with Metriport.

string

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

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"
  }
}

`patient.discharge-summary`

A Patient Discharge Summary event is sent after a patient.discharge notification when Metriport locates a matching discharge summary from the HIE. At most one successful patient.discharge-summary is sent per encounter. The url is a FHIR collection Bundle of resources from the matching source document, not the ADT Patient Encounter Bundle.

Schema

required

Metadata about the message.

Show meta properties

string

required

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

DischargeSummaryWebhookPayload

required

Show payload properties

string

required

The URL to download a FHIR collection Bundle containing resources from the matching HIE discharge summary document (for example Composition, Encounter, DocumentReference, and related clinical data for that patient). It’s valid for 10 minutes.

string

required

The Metriport encounter/stay id this summary is tied to. The same value is sent as meta.requestId.

Example payload

{
  "meta": {
    "messageId": "00000000-0000-0000-0000-000000000000",
    "requestId": "11111111-1111-1111-1111-111111111111",
    "when": "2025-01-30T23:15:01.000Z",
    "type": "patient.discharge-summary"
  },
  "payload": {
    "url": "<presigned-download-url>",
    "patientId": "metriport-patient-uuid",
    "encounterId": "11111111-1111-1111-1111-111111111111",
    "externalId": "your-first-party-id",
    "additionalIds": {
      "athenahealth": ["00000"]
    }
  }
}

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.

​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.pre-admit

​Schema

​Example payload

​patient.register

​Schema

​Example payload

​patient.admit

​Schema

​Example payload

​patient.visit-update

​Schema

​Example payload

​patient.transfer

​Schema

​Example payload

​patient.discharge

​Schema

​Example payload

​patient.discharge-summary

​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.pre-admit`

Schema

Example payload

`patient.register`

Schema

Example payload

`patient.admit`

Schema

Example payload

`patient.visit-update`

Schema

Example payload

`patient.transfer`

Schema

Example payload

`patient.discharge`

Schema

Example payload

`patient.discharge-summary`

Schema

Example payload

Additional Resources

FHIR Encounter