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 five 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
Message	`message.*`	Outbound delivery status and inbound messages from external practitioners
Patient Notifications	`patient.*`	Real-time notifications (ADTs, pharmacy, laboratory)
Individual Access (IAS)	`ias.*`	Identity verification for IAS flows

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",
      "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",
      "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.

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-paged`	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-paged`

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. When there are many documents, the payload is automatically split into multiple webhook pages to keep each under 200KB. Each page shares the same requestId but has a unique messageId. Use the pagination field to determine the current page number and total pages.

Download URLs are valid for 10 minutes
Pages are sent sequentially with a 50ms delay between them

If you’re receiving the legacy medical.document-bulk-download-urls webhook, please contact us to migrate to medical.document-bulk-download-paged.

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-paged"
  },
  "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>",
          "downloadUrl": "https://api.metriport.com/medical/v1/document/download-url?fileName=..."
        }
      ],
      "pagination": {
        "page": 1,
        "totalPages": 3,
        "totalItems": 150
      }
    }
  ]
}

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-paged.

requestId

string

required

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

patients

DocumentBulkDownloadPage[]

required

An array containing the patient data with document references. When there are many documents, they are split into multiple webhook payloads (pages) to keep each payload under 200KB.

Show DocumentBulkDownloadPage properties

patientId

string

required

The Patient ID.

status

string

required

The outcome of the step corresponding to type - can be one of completed | failed.

documents

DocumentReferenceWithDownloadURL[]

An array of objects describing the Documents that can be retrieved for the Patient along with the downloadable URLs to retrieve them. Each document has two URL properties:

url: The presigned URL for direct download (expires in ~10 minutes)

downloadUrl: The Metriport API endpoint to retrieve a fresh presigned URL if the original has expired

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.

organizationIdentifiers

object[]

Organizations associated with the document, when available. Each entry may include a display name and identifier values.

Show Organization identifier properties

name

string

Human-readable organization name.

identifierValues

string[]

Identifier values for the organization (for example, OID-style strings).

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.

pagination

object

required

Pagination metadata for this page of the bulk download response.

Show pagination properties

page

integer

required

The current page number, starting at 1.

totalPages

integer

required

The total number of webhook pages for this bulk download request.

totalItems

integer

required

The total number of documents across all webhook pages for this bulk download request.

When documents are split across multiple webhook pages, all pages share the same requestId but each has a unique messageId in the meta field. Use the pagination field to determine the current page number and the total number of pages (totalPages).

Webhooks are sent sequentially with a 50ms delay between pages to avoid overwhelming your webhook endpoint.

Message Events

Prefix: message.*

Message events cover both directions of secure messaging - outbound delivery status for messages you send, and inbound notifications when another practitioner sends a message to you.

Event Types

Event	Description
`message.status`	Final delivery status for an outbound Send Message request
`message.received`	A new message received from another practitioner

`message.status`

You’ll receive this webhook after invoking POST Send Message. The payload reports the final delivery status of the message — either when the recipient acknowledges receipt, or when delivery fails. You will receive one webhook per send request, with a status of completed or failed based on the outcome of the operation. Recommended flow:

Call Send Message for a patient
Receive this webhook when delivery completes or fails
Optionally confirm status via Get Message Status

Example Payloads

Completed (recipient acknowledged receipt):

{
  "meta": {
    "requestId": "00000000-0000-0000-0000-000000000000",
    "when": "2026-06-16T18:42:11.000Z",
    "type": "message.status"
  },
  "payload": {
    "id": "00000000-0000-0000-0000-000000000000",
    "patientId": "00000000-0000-0000-0000-000000000000",
    "status": "completed",
    "updatedAt": "2026-06-16T18:42:11.000Z"
  }
}

Schema Reference

meta

required

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

Show meta properties

type

string

required

Always message.status.

requestId

string

required

The ID of the send message request that initiated this webhook. Matches the messageId returned by Send Message.

payload

Message

required

The message delivery status.

Show Message properties

string

required

The ID of the message. Matches the messageId returned by Send Message.

patientId

string

required

The Patient ID the message relates to.

status

string

required

One of completed or failed. completed means the recipient acknowledged receipt.

updatedAt

string

required

ISO 8601 timestamp of when the message reached its final status.

reason

string

Reason for failure. Only present when status is failed.

`message.received`

You’ll receive this webhook when another practitioner sends a secure message to your organization. The payload includes the message metadata and a presigned URL to download the full message content and attachments. Recommended flow:

Receive this webhook
Download the message from the url in the payload
Process the message and associated patient data in your application

Example Payload

{
  "meta": {
    "requestId": "00000000-0000-0000-0000-000000000000",
    "when": "2026-06-16T18:42:11.000Z",
    "type": "message.received"
  },
  "payload": {
    "url": "<presigned-download-url>",
    "id": "00000000-0000-0000-0000-000000000000",
    "patientId": "00000000-0000-0000-0000-000000000000",
    "sender": "direct.example@hospital.org",
    "intendedRecipients": ["Dr. John Doe", "1234567890"],
    "subject": "Consult Summary",
    "receivedAt": "2026-06-16T18:42:11.000Z"
  }
}

Schema Reference

meta

required

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

Show meta properties

requestId

string

required

The ID of the send message request that initiated this webhook. Matches the messageId returned by Send Message.

type

string

required

Always message.received.

payload

ReceivedMessage

required

The received message details.

Show ReceivedMessage properties

url

string

required

A presigned URL to download the full message content. Valid for 3 minutes.

string

required

The ID of the received message.

patientId

string

The Patient ID the message relates to, if Metriport was able to match the message to a patient in your account.

sender

string

required

The Direct address or OID of the sending organization.

intendedRecipients

string[]

The NPIs or short string descriptions of intended recipients

subject

string

required

The subject line of the message.

receivedAt

string

required

ISO 8601 timestamp of when the message was received.

Patient Notification Events

Prefix: patient.*

Patient Notification events provide real-time ADT (Admission, Discharge, Transfer), Pharmacy, and/or Laboratory updates. These are part of Real-time Patient Notifications.

Event Types

Event	Description
`patient.laboratory`	Patient has received Laboratory data
`patient.pharmacy`	Patient has received Medication data
`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.

Individual Access (IAS) Events

Prefix: ias.*

IAS-specific events are delivered to the same webhook URL you configure for the Medical API. For the full Individual Access flow, see Individual Access (IAS).

Event Types

Event	Description
`ias.identity.verified`	The user completed hosted identity verification; includes `proofedIdentityId` for IAS queries

`ias.identity.verified`

Sent when the user successfully completes the hosted identity session started with Create Identity Session. Store the proofedIdentityId from this payload and pass it on Start Network Query requests where the purposeOfUse query parameter is ias. Example payload:

{
  "meta": {
    "messageId": "33333333-3333-3333-3333-333333333333",
    "when": "2026-04-29T14:52:11.000Z",
    "type": "ias.identity.verified",
    "data": {
      "sessionId": "ids_018f7c2f..."
    }
  },
  "payload": {
    "patientId": "018f7c31-bbbb-7bbb-7bbb-7bbbbbbbbbbb",
    "proofedIdentityId": "pid_018f7c30-aaaa-4aaa-4aaa-4aaaaaaaaaaa",
    "status": "active"
  }
}

Field	Description
`patientId`	Metriport patient the verified identity is attached to
`proofedIdentityId`	Identifier to pass as `proofedIdentityId` on IAS network queries
`status`	Identity record status (for example `active`)

Any metadata you supplied when creating the identity session is echoed under meta.data when configured for your integration.

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
);

​Overview

​Webhook Categories

​Network Query Events

​Event Types

​Medical Data Events

​Event Types

​medical.consolidated-data

​medical.bulk-patient-create

​medical.document-bulk-download-paged

​Message Events

​Event Types

​message.status

​message.received

​Patient Notification Events

​Event Types

Full Documentation

​Individual Access (IAS) Events

​Event Types

​ias.identity.verified

​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-paged`

Message Events

Event Types

`message.status`

`message.received`

Patient Notification Events

Event Types

Individual Access (IAS) Events

Event Types

`ias.identity.verified`

Passing Metadata