Receiving Webhooks

Overview

Metriport sends webhook messages to your app as data becomes available in our system. This allows you to react to events in real-time rather than polling for updates. For information on how to set up webhooks, see Implementing Webhooks.

When you receive a webhook message, you should respond with a 200 status code within 4 seconds. We recommend processing the webhook request asynchronously.

Webhook Categories

Metriport webhooks are organized into three categories based on their event type prefix:

Category	Prefix	Purpose
Network Query	`network-query.*`	Data retrieval from health networks (HIEs, pharmacies, labs)
Medical Data	`medical.*`	Consolidated data, bulk operations, and document downloads
Patient Notifications	`patient.*`	Real-time ADT events (admissions, transfers, discharges)

Network Query Events

Prefix: network-query.*

Network Query events are emitted when you start a Network Query to retrieve patient data from health networks. You receive one webhook per source as each completes. Recommended flow:

Start a Network Query for a patient
Receive network-query.* webhooks as each source completes
Download the patient record from the consolidatedDataUrl in the payload

Event Types

Event	Description
`network-query.hie`	HIE data (documents from Health Information Exchanges) is ready
`network-query.pharmacy`	Pharmacy data (medication prescription and pickup history) is ready
`network-query.lab`	Laboratory data (lab results) is ready

Each webhook includes a consolidatedDataUrl - a presigned S3 URL to download the patient’s aggregated record, i.e. their ‘consolidated data’. This allows you to reingest the record as soon as any data source is ready.

Example Payloads

HIE Example:

{
  "meta": {
    "messageId": "11111111-1111-1111-1111-111111111111",
    "requestId": "22222222-2222-2222-2222-222222222222",
    "when": "2024-12-26T10:03:22.000Z",
    "type": "network-query.hie",
    "data": {
      "youCan": "putAny",
      "stringKeyValue": "pairsHere"
    }
  },
  "payload": {
    "patientId": "00000000-0000-0000-0000-000000000000",
    "externalId": "1234567890",
    "consolidatedDataUrl": "https://documents.s3.amazonaws.com/consolidated-abc123-Amz-SignedHeaders=host",
    "source": {
      "type": "hie",
      "status": "completed",
      "completedAt": "2024-12-26T10:03:20.000Z"
    }
  }
}

Pharmacy Example:

{
  "meta": {
    "messageId": "11111111-1111-1111-1111-111111111111",
    "requestId": "22222222-2222-2222-2222-222222222222",
    "when": "2024-12-26T10:04:15.000Z",
    "type": "network-query.pharmacy",
    "data": {
      "youCan": "putAny",
      "stringKeyValue": "pairsHere"
    }
  },
  "payload": {
    "patientId": "00000000-0000-0000-0000-000000000000",
    "externalId": "1234567890",
    "consolidatedDataUrl": "https://documents.s3.amazonaws.com/consolidated-abc123-Amz-SignedHeaders=host",
    "source": {
      "type": "pharmacy",
      "source": "surescripts",
      "status": "completed",
      "completedAt": "2024-12-26T10:04:12.000Z"
    }
  }
}

Lab Example:

{
  "meta": {
    "messageId": "11111111-1111-1111-1111-111111111111",
    "requestId": "22222222-2222-2222-2222-222222222222",
    "when": "2024-12-26T10:05:30.000Z",
    "type": "network-query.lab",
    "data": {
      "youCan": "putAny",
      "stringKeyValue": "pairsHere"
    }
  },
  "payload": {
    "patientId": "00000000-0000-0000-0000-000000000000",
    "externalId": "1234567890",
    "consolidatedDataUrl": "https://documents.s3.amazonaws.com/consolidated-abc123-Amz-SignedHeaders=host",
    "source": {
      "type": "lab",
      "source": "quest",
      "status": "completed",
      "completedAt": "2024-12-26T10:05:28.000Z"
    }
  }
}

Schema Reference

meta

required

Metadata about the message. The full format is described here.

Show meta properties

type

string

required

The type of the Network Query webhook message. Can be one of: network-query.hie, network-query.pharmacy, network-query.lab.

requestId

string

required

The ID of the Network Query request that initiated this webhook. Use this to correlate webhooks with your original query.

data

object

The metadata you passed when starting the Network Query.

payload

NetworkQueryPayload

required

The network query result payload for the patient.

Show NetworkQueryPayload properties

patientId

string

required

The Patient ID.

externalId

string

The external ID you provided when creating the patient.

consolidatedDataUrl

string

required

A presigned S3 URL to download the patient’s consolidated data. Valid for 3 minutes.

source

Source

required

Information about the data source.

Show Source properties

type

string

required

The type of source: hie, pharmacy, or lab.

source

string

The specific source provider (e.g., surescripts, quest). Only present for pharmacy and lab sources.

status

string

required

The status of this source: completed or failed.

completedAt

string

required

ISO 8601 timestamp of when this source query completed.

Medical Data Events

Prefix: medical.*

Medical Data events are emitted for consolidated data queries, bulk operations, and document downloads. Unlike Network Query events which are triggered automatically after data retrieval, these events are triggered by explicit API calls.

Event Types

Event	Description
`medical.consolidated-data`	Result of a Consolidated Data Query
`medical.bulk-patient-create`	Status updates for Bulk Patient Create
`medical.document-bulk-download-urls`	Download URLs for Bulk Document Download

`medical.consolidated-data`

You’ll receive this webhook after invoking a Consolidated Query via POST Start Consolidated Data Query. The payload contains the patient’s consolidated medical record as deduplicated, standardized FHIR data. This includes all converted documents from network queries plus any FHIR data your application has inserted directly. Note that inside the Bundle you’ll find a DocumentReference resource with attachments in the content array:

The first item contains an attachment with a url which can be used to download the data.
If requested conversionType is json, an additional attachment with contentType: "application/gzip" provides a gzip-compressed copy for faster downloads.
Download URLs are valid for 3 minutes

If there was no data available for the Patient, the Bundle will be empty (the entry array will have no elements).

Recommended flow:

Call Start Consolidated Data Query for a patient
Receive this webhook
Download the data from the presigned URLs in the bundle

Example Payload

{
  "meta": {
    "messageId": "11111111-1111-1111-1111-111111111111",
    "requestId": "22222222-2222-2222-2222-222222222222",
    "when": "2023-08-23T22:09:11.373Z",
    "type": "medical.consolidated-data"
  },
  "patients": [
    {
      "patientId": "00000000-0000-0000-0000-000000000000",
      "externalId": "1234567890",
      "additionalIds": {
        "athenahealth": ["99992"]
      },
      "status": "completed",
      "filters": {
        "resources": "Encounter,Observation"
      },
      "bundle": {
        "resourceType": "Bundle",
        "total": 1,
        "type": "collection",
        "entry": [
          {
            "resource": {
              "resourceType": "DocumentReference",
              "subject": {
                "reference": "Patient/00000000-0000-0000-0000-000000000000"
              },
              "content": [
                {
                  "attachment": {
                    "contentType": "application/json",
                    "url": "https://documents.s3.amazonaws.com/abc123-Amz-SignedHeaders=host"
                  }
                },
                {
                  "attachment": {
                    "contentType": "application/gzip",
                    "url": "https://documents.s3.amazonaws.com/abc123.gz-Amz-SignedHeaders=host"
                  }
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

Schema Reference

meta

required

Metadata about the message. The full format is described here.

Show meta properties

type

string

required

Always medical.consolidated-data.

requestId

string

required

The ID of the consolidated data query that initiated this webhook.

patients

PatientConsolidatedData[]

required

Array of consolidated data query results - one item per patient.

Show PatientConsolidatedData properties

patientId

string

required

The Patient ID.

externalId

string

The external ID you provided when creating the patient.

additionalIds

object

Additional IDs for the patient from integrated EHR systems.

status

string

required

The outcome: completed or failed.

filters

Filter

required

The filters applied to the query.

Show Filter properties

resources

string

Comma-separated list of FHIR resource types returned.

dateFrom

string

Start date filter - formatted YYYY-MM-DD.

dateTo

string

End date filter - formatted YYYY-MM-DD.

bundle

Bundle

A FHIR Bundle containing a DocumentReference with presigned download URLs.

`medical.bulk-patient-create`

You’ll receive this webhook after invoking a bulk patient creation via POST Bulk Create Patient. The payload reports the status of the bulk creation job, allowing you to process large CSV files of patient demographics asynchronously. Note that you’ll receive multiple webhooks for a single bulk create request:

First, a webhook with status: "processing" confirming the job started
Then, a webhook with status: "completed" containing a presigned URL to download the results CSV with created patient IDs
Or, a webhook with status: "failed" containing a reason explaining what went wrong
Download URLs are valid for 3 minutes

Recommended flow:

Call Bulk Create Patient with a CSV file
Receive webhooks as the job progresses
Download the results CSV from the presigned URL

Example Payload

{
  "meta": {
    "messageId": "11111111-1111-1111-1111-111111111111",
    "requestId": "22222222-2222-2222-2222-222222222222",
    "when": "2024-12-30T05:05:12.215Z",
    "type": "medical.bulk-patient-create"
  },
  "bulkPatientCreate": {
    "requestId": "22222222-2222-2222-2222-222222222222",
    "status": "completed",
    "result": "<presigned-download-url>"
  }
}

Schema Reference

meta

required

Metadata about the message. The full format is described here.

Show meta properties

type

string

required

Always medical.bulk-patient-create.

requestId

string

required

The ID of the bulk create request that initiated this webhook.

bulkPatientCreate

BulkPatientCreate

required

The bulk patient create job status.

Show BulkPatientCreate properties

requestId

string

required

The ID of this bulk patient create job.

status

string

required

One of processing, completed, or failed.

reason

string

Reason for failure. Only present when status is failed.

result

string

Presigned URL to download the results CSV. Valid for 3 minutes. Only present when status is completed.

`medical.document-bulk-download-urls`

You’ll receive this webhook after invoking a bulk document download via POST Bulk Get Document URL. The payload provides presigned download URLs for all documents belonging to the specified patients, allowing you to efficiently download multiple documents in bulk. Note that the payload contains a patients array with results for each patient:

Each patient entry includes a status (completed or failed) and a documents array
Each document includes metadata (id, fileName, mimeType, etc.) and a presigned url
Download URLs are valid for 10 minutes

Recommended flow:

Call Bulk Get Document URL with patient IDs
Receive this webhook
Download documents using the presigned URLs before they expire

Example Payload

{
  "meta": {
    "messageId": "11111111-1111-1111-1111-111111111111",
    "requestId": "22222222-2222-2222-2222-222222222222",
    "when": "2023-11-30T05:05:12.215Z",
    "type": "medical.document-bulk-download-urls"
  },
  "patients": [
    {
      "status": "completed",
      "patientId": "00000000-0000-0000-0000-000000000000",
      "externalId": "1234567890",
      "additionalIds": {
        "athenahealth": ["99992"]
      },
      "documents": [
        {
          "id": "33333333-3333-3333-3333-333333333333",
          "size": 40670,
          "fileName": "document.xml",
          "description": "Patient Diagnoses",
          "status": "current",
          "indexed": "2019-09-07T15:50:00.000Z",
          "mimeType": "application/xml",
          "url": "<presigned-download-url>"
        }
      ]
    }
  ]
}

Schema Reference

meta

required

Metadata about the message. The full format is described here.

Show meta properties

type

string

required

Always medical.document-bulk-download-urls.

requestId

string

required

The ID of the bulk download request that initiated this webhook.

patients

DocumentBulkDownloadUrls[]

required

Array of results per patient.

Show DocumentBulkDownloadUrl properties

patientId

string

required

The Patient ID.

externalId

string

The external ID you provided when creating the patient.

additionalIds

object

Additional IDs for the patient from integrated EHR systems.

status

string

required

completed or failed.

documents

DocumentReferenceWithURL[]

Array of documents with download URLs. Valid for 10 minutes.

Show DocumentReference properties

string

required

The Document ID.

url

string

required

The URL for downloading the document.

fileName

string

required

Name of the file.

description

string

Human-readable description of the Document.

status

string

Can be one of current, superceded, or entered in error.

indexed

string

When this Document reference was created - formatted to ISO 8601.

mimeType

string

Document MIME type - usually application/xml, or application/pdf.

size

string

Size of the Document in bytes.

type

CodableConcept

What kind of document this is (LOINC if possible).

Show CodableConcept properties

coding

Coding[]

Array containing the coding defined by a terminology system.

Show Coding properties

system

string

Identity of the terminology system.

code

string

Symbol in syntax defined by the system.

display

string

Representation defined by the system.

text

string

Plain text representation of the concept.

Patient Notification Events

Prefix: patient.*

Patient Notification events provide real-time ADT (Admission, Discharge, Transfer) updates as patients move through healthcare facilities. These are part of Real-time Patient Notifications.

Event Types

Event	Description
`patient.admit`	Patient has been admitted to a healthcare facility
`patient.transfer`	Patient has been transferred between locations
`patient.discharge`	Patient has been discharged from a healthcare facility

To enable patient notifications, configure them in a Cohort and associate the patients you want to monitor.

Each webhook includes a url to download a FHIR Bundle containing the complete encounter data.

Example Payload (patient.admit)

{
  "meta": {
    "messageId": "11111111-1111-1111-1111-111111111111",
    "requestId": "22222222-2222-2222-2222-222222222222",
    "when": "2025-01-30T23:00:01.000Z",
    "type": "patient.admit"
  },
  "payload": {
    "url": "<presigned-download-url>",
    "patientId": "00000000-0000-0000-0000-000000000000",
    "externalId": "1234567890",
    "additionalIds": {
      "athenahealth": ["99992"]
    },
    "admitTimestamp": "2025-01-28T23:00:00.000Z"
  }
}

Full Documentation

See the complete Real-time Patient Notifications guide for detailed schemas, all event types, and the FHIR Encounter model.

Passing Metadata

You can pass metadata when calling endpoints that support webhooks. This metadata will be returned in the meta.data field of the webhook. You may use this to attach whatever metadata is relevant for your use-case - for example, external IDs. Below is an example payload you could send in the request body of one of those endpoints and how you would use the sdk: Note that the metadata param supports up to 50 custom string key-value pairs, with keys up to 40 chars, and values of up to 500 chars.

{
  "metadata": {
     "youCan": "putAny",
     "stringKeyValue": "pairsHere",
  }
}

Metriport SDK

import { MetriportMedicalApi } from "@metriport/api-sdk";

const metadata = {
    youCan: "putAny",
    stringKeyValue: "pairsHere",
};

const metriport = new MetriportMedicalApi(apiToken);

const consolidatedData = await metriport.startConsolidatedQuery(
  patientId,
  ["AllergyIntolerance", "Appointment"] as const,
  "2023-03-01",
  "2023-04-01",
  undefined,
  metadata
);

Getting Started

API Reference

Handling Data

FHIR

API Tools

More Info

Legacy API Reference

Receiving Webhooks

Overview

Webhook Categories

Network Query Events

Event Types

Medical Data Events

Event Types

`medical.consolidated-data`

`medical.bulk-patient-create`

`medical.document-bulk-download-urls`

Patient Notification Events

Event Types

Full Documentation

Passing Metadata

Getting Started

API Reference

Handling Data

FHIR

API Tools

More Info

Legacy API Reference

​Overview

​Webhook Categories

​Network Query Events

​Event Types

​Medical Data Events

​Event Types

​medical.consolidated-data

​medical.bulk-patient-create

​medical.document-bulk-download-urls

​Patient Notification Events

​Event Types

Full Documentation

​Passing Metadata

Overview

Webhook Categories

Network Query Events

Event Types

Medical Data Events

Event Types

`medical.consolidated-data`

`medical.bulk-patient-create`

`medical.document-bulk-download-urls`

Patient Notification Events

Event Types

Passing Metadata