Receiving Webhooks (Legacy)

Legacy Webhook Flow: This page documents webhooks for the legacy Document Query flow. We recommend migrating to the Network Query flow, which provides a unified way to query all health data networks (HIEs, pharmacies, and laboratories) with improved webhook events. See the updated webhooks guide for details.

Overview

When using the Medical API, Metriport will send Webhook messages to your app as soon as data becomes available. This is the usual flow to obtain Patient data:

You trigger a document query to retrieve a Patient’s medical documents from HIEs;
- XML C-CDA documents will be converted and stored on Metriport’s FHIR storage;
- as documents get downloaded and converted, you should get patient document data webhook messages;
Once document conversion is completed, you can query for patient consolidated data;
- depending on the amount of data this can take some time to crunch together, so results are sent through a webhook message: patient consolidated data

You should expect to get more than one Webhook message per patient per request (document query and/or consolidated data). To enable this integration approach with Metriport, and for some prerequesite reading to understand how the Webhook flow works, see our Webhooks guide.

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

Types of Messages

medical.document-download: result of Document Query, containing the newly downloaded documents for the patient - see details below;
medical.document-conversion: result of converting the newly downloaded C-CDA documents into FHIR - see details below;
medical.document-bulk-download-urls: list of download urls for a patient’s documents, see details below;
medical.consolidated-data: result of a Consolidated Data Query, containing the patient’s data in FHIR format - see details below.
medical.bulk-patient-create: updates for a Bulk Patient Create
- see details below.

Workflow

Download URLs

Below is a flowchart of the process to download all the raw documents we’ve received from the networks for a patient:

Consolidated Data

Below is a flowchart of the process to get a patient’s consolidated FHIR data:

Passing Metadata

You can pass metadata to endpoints that support webhooks, and you will receive the meta.data field of the webhook request. Metadata holds a record of up to 50 custom string key-value pairs. Key names can be up to 40 characters long and values up to 500 characters long. 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:

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

Patient Document Data

These are messages you can expect to receive in the following scenarios:

When queried documents have completed downloading, the message type will be medical.document-download, and at this point you’ll be able to download the raw files;
Then when the conversion to FHIR has completed, the message type will be medical.document-conversion, and at this point you’ll be able to query for patient consolidated data in FHIR-compliant format.

Note that the webhooks will only contain updates for new data fetched in the current document query.

{
  "meta": {
    "messageId": "<message-id>",
    "requestId": "<request-id>",
    "when": "<date-time-in-utc>",
    "type": "medical.document-download",
    "data": {
        "youCan": "putAny",
        "stringKeyValue": "pairsHere"
    }
  },
  "patients": [
    {
      "patientId": "eddeefa1-b54a-41d6-854f-0e91b7871d6a",
      "externalId": "1234567890",
      "additionalIds": {
        "athenahealth": ["99992"]
      },
      "type": "document-download",
      "status": "completed",
      "documents": [
        {
          "id": "1.2.543.1.34.1.34.134",
          "fileName": "CCDA_Diag.xml",
          "description": "Patient Diagnoses",
          "status": "current",
          "indexed": "2019-09-07T15:50:00.000Z",
          "mimeType": "application/xml",
          "size": "17344007",
          "type": {
            "coding": [
              {
                "system": "http://snomed.info/sct",
                "code": "62479008",
                "display": "Diagnoses"
              }
            ],
            "text": "Diagnoses"
          }
        },
        {
          "id": "1.2.543.1.224.54.22.540",
          "fileName": "Progress_Notes.xml",
          "description": "Patient Encounter Progress Notes 2023-03-22",
          "status": "current",
          "indexed": "2023-03-22T08:34:00.000Z",
          "mimeType": "application/xml",
          "size": "8675545",
          "type": {
            "coding": [
              {
                "system": "http://snomed.info/sct",
                "code": "371532007",
                "display": "Progress Report"
              }
            ],
            "text": "Progress Notes"
          }
        }
      ]
    },
    {
      "patientId": "<patient-id-2>",
      "type": "document-download",
      "status": "completed",
      ...
    }
  ]
}

The format follows:

required

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

Show meta type property details

string

required

The type of the Medical API webhook data message. Can be one of: medical.document-download, medical.document-conversion, medical.consolidated-data, medical.document-bulk-download-urls.

PatientDocQueryUpdate[]

required

Array of Document query status updates - where each item corresponds to a specific patient.

Show PatientDocQueryUpdate properties

string

required

The Patient ID.

string

required

Specifies what step in the Document query flow this message is for - can be one of document-download | document-conversion.

string

required

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

DocumentReference[]

An array of objects describing the Documents that can be retrieved for the Patient - will only be present for document-download messages.

Show DocumentReference properties

string

required

The Document ID.

string

required

Name of the file.

string

Human-readable description of the Document.

string

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

string

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

string

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

string

Size of the Document in bytes.

CodableConcept

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

Show CodableConcept properties

Coding[]

Array containing the coding defined by a terminology system.

Show Coding properties

string

Identity of the terminology system.

string

Symbol in syntax defined by the system.

string

Representation defined by the system.

string

Plain text representation of the concept.

Patient Consolidated Data

A Patient’s consolidated data is the result of converting all C-CDA documents into deduplicated and standardized FHIR, as well as other FHIR data your application has inserted into Metriport’s FHIR repository. This data can be retrieved in either FHIR JSON format, or a rendered PDF or HTML Medical Record Summary. Patients can have a large amount of data, so in order to have access to a Patient’s data:

Trigger a consolidated data query - one query per patient at any given time;
Your app can check the status by calling get consolidated query status (optional);
When the result is ready, we’ll send a webhook message with the results (below).

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.

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

Example payload:

{
  "meta": {
    "messageId": "1e82424a-1220-473d-a0d1-6e5fde15159e",
    "requestId": "00000000-0000-0000-0000-000000000000",
    "when": "2023-08-23T22:09:11.373Z",
    "type": "medical.consolidated-data"
  },
  "patients": [
    {
      "patientId": "eddeefa1-b54a-41d6-854f-0e91b7871d6a",
      "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/eddeefa1-b54a-41d6-854f-0e91b7871d6a"
              },
              "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"
                  }
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

The format follows:

required

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

Show meta type property details

string

required

For Patient Consolidated Data this will always be medical.consolidated-data.

PatientConsolidatedData[]

required

Array of consolidated data query results - where each item corresponds to a specific patient.

Show PatientConsolidatedData properties

string

required

The Patient ID.

string

required

The outcome of consolidated data query - can be one of completed | failed.

Filter[]

required

The filters used to obtain the patient’s consolidated data.

Show Filter properties

string

A comma separated, case sensitive list of resources to be returned. If none are provided all resources will be included.

string

The start date (inclusive) for which to filter returned resources - formatted YYYY-MM-DD as per ISO 8601. If not provided, no start date filter will be applied.

string

The end date (inclusive) for which to filter returned resources - formatted YYYY-MM-DD as per ISO 8601. If not provided, no end date filter will be applied.

Bundle

A FHIR Bundle containing a DocumentReference resource with attachments in the content array. For JSON requests, two attachments are provided:

Main attachment with the requested format (JSON, HTML, or PDF)
Gzip-compressed attachment (JSON only) with contentType: "application/gzip" for faster downloads

Each attachment has a url which is valid for 10 minutes.

Bulk Patient Create

During the processing of a Bulk Patient Create, the Metriport API sends Webhook messages of type medical.bulk-patient-create to indicate the status update and provide relevant information. You can expect to get two messages of this type for each Bulk Patient Create, with the status being the main difference between each:

First message:
- processing: the CSV file has been uploaded and is being processed;
Second message - one of:
- completed: the bulk create is completed - includes the result CSV file;
- failed: the bulk create failed (likely due to the uploaded file being invalid).

The URL will only be valid for 600 seconds (10 minutes).

Example payload:

{
  "meta": {
    "messageId": "1e82424a-1220-473d-a0d1-6e5fde15159e",
    "requestId": "00000000-0000-0000-0000-000000000000",
    "when": "2024-12-30T05:05:12.215Z",
    "type": "medical.bulk-patient-create"
  },
  "bulkPatientCreate": {
    "requestId": "00000000-00000000-00000000-00000000",
    "status": "completed",
    "result": "<presigned-download-url>"
  }
}

The format follows:

required

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

Show meta type property details

string

required

For Bulk Patient Create this will always be medical.bulk-patient-create.

BulkPatientCreate

required

The information about the Bulk Patient Create request.

Show BulkPatientCreate properties

string

required

The ID that represents this bulk patient create.

string

required

The status of the bulk create. One of processing, failed, or completed. See all the possible values here.

string

The reason for a failed bulk create. Only present if the status is failed.

string

The URL to download the CSV file containing the result of the Bulk Patient Create. It’s valid for 10 minutes. Only present if the status is completed.

Result CSV File

The message medical.bulk-patient-create with status completed includes a URL in the result field, which you can use to download the result of the Bulk Patient Create.

The URL will only be valid for 600 seconds (10 minutes).

The file is based on the same format as the input CSV, with the following additional columns:

string

The ID of the Patient on Metriport - only provided if the Patient was created successfully.

string

required

Whether the respective demographics was accepted and used to create a Patient. Can be one of succeeded or failed.

string

If the patient failed to be created, this indictes the reason for failure. Only included if the patient fails to be created.

An example of a result file can be accessed here.

Bulk Document Download URLs

If you want to download all of a patient’s documents, you can start a Bulk Get Document URL query.

The URLs will only be valid for 600 seconds (10 minutes).

This webhook includes all document metadata and download URLs directly in the payload. Here is an example:

{
  "meta": {
    "messageId": "11111111-1111-1111-1111-111111111111",
    "requestId": "00000000-0000-0000-0000-000000000000",
    "when": "2023-11-30T05:05:12.215Z",
    "type": "medical.document-bulk-download-urls"
  },
  "patients": [
    {
      "status": "completed",
      "patientId": "22222222-2222-2222-2222-222222222222",
      "externalId": "1234567890",
      "additionalIds": {
        "athenahealth": ["00000"]
      },
      "documents": [
        {
          "id": "33333333-3333-3333-3333-333333333333",
          "size": 40670,
          "fileName": "33333333-3333-3333-3333-333333333333/22222222-2222-2222-2222-222222222222/33333333-3333-3333-3333-333333333333_22222222-2222-2222-2222-222222222222_00000000-0000-0000-0000-000000000000.xml",
          "description": "Patient Diagnoses",
          "status": "current",
          "indexed": "2019-09-07T15:50:00.000Z",
          "mimeType": "application/xml",
          "type": {
            "coding": [
              {
                "system": "http://snomed.info/sct",
                "code": "62479008",
                "display": "Diagnoses"
              }
            ],
            "text": "Diagnoses"
          },
          "url": "<a-document-url>",
          "organizationIdentifiers": [
            {
              "name": "Org1",
              "identifierValues": ["1.1.1.1.1.1"]
            }
          ]
        }
      ]
    }
  ]
}

The format is as follows:

required

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

Show Details of the 'meta' type property

string

required

The type of the Medical API webhook data message. In this case, it will be medical.document-bulk-download-urls.

DocumentBulkDownloadUrls[]

required

An array of Document bulk download URLs, where each item corresponds to the queried patient.

Show DocumentBulkDownloadUrl properties

string

required

The Patient ID.

string

required

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

DocumentReferenceWithURL[]

An array of objects describing the Documents that can be retrieved for the Patient along with the downloadable url to retrieve them.

Show DocumentReference properties

string

required

The Document ID.

string

required

The URL for downloading the document.

string

required

Name of the file.

string

Human-readable description of the Document.

string

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

string

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

string

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

string

Size of the Document in bytes.

object[]

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

Show Organization identifier properties

string

Human-readable organization name.

string[]

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

CodableConcept

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

Show CodableConcept properties

Coding[]

Array containing the coding defined by a terminology system.

Show Coding properties

string

Identity of the terminology system.

string

Symbol in syntax defined by the system.

string

Representation defined by the system.

string

Plain text representation of the concept.

Getting Started

API Reference

Handling Data

FHIR

API Tools

More Info

Legacy API Reference

Receiving Webhooks (Legacy)

Overview

Types of Messages

Workflow

Download URLs

Consolidated Data

Passing Metadata

Patient Document Data

Patient Consolidated Data

Bulk Patient Create

Result CSV File

Bulk Document Download URLs

​Overview

​Types of Messages

​Workflow

​Download URLs

​Consolidated Data

​Passing Metadata

​Patient Document Data

​Patient Consolidated Data

​Bulk Patient Create

​Result CSV File

​Bulk Document Download URLs

Overview

Types of Messages

Workflow

Download URLs

Consolidated Data

Passing Metadata

Patient Document Data

Patient Consolidated Data

Bulk Patient Create

Result CSV File

Bulk Document Download URLs