MessageHeader — Messaging routing header

The FHIR equivalent of HL7 v2's MSH segment. Always the first entry of a Bundle of type message, it carries sender, receiver, event and routing data.

Purpose

FHIR messaging is one of the four interoperability paradigms (alongside REST, documents, services). It consists of carrying a Bundle of type message containing a business event — typically clinical or administrative — from a sending system to a receiver, with asynchronous acknowledgment.

MessageHeader is required to be the first entry of that Bundle. It carries the routing semantics: event code, source, destination, focus (subject), reason, and optionally the asynchronous response to a previous message.

Key fields

FHIR messaging pattern

The typical FHIR messaging exchange:

1. System A builds a Bundle type=message with MessageHeader as the first entry and clinical resources following.
2. A POSTs the Bundle to [base]/$process-message on receiver B.
3. B answers either:
   • Synchronous: an immediate message-response Bundle with MessageHeader response.code=ok.
   • Asynchronous: 202 Accepted, then later B POSTs a response Bundle to A's source.endpointUrl.

JSON example

A MessageHeader notifying a patient admission (admin-notify) with an Encounter in focus:

{
  "resourceType": "MessageHeader",
  "id": "example",
  "eventCoding": {
    "system": "http://example.org/fhir/message-events",
    "code": "admin-notify"
  },
  "destination": [{
    "name": "PMS",
    "endpointUrl": "https://pms.example.org/fhir/messaging",
    "receiver": { "reference": "Organization/pms-org" }
  }],
  "sender": { "reference": "Organization/hospital-1" },
  "author": { "reference": "Practitioner/dr-jones" },
  "source": {
    "name": "HIS",
    "software": "Acme HIS v3.4",
    "version": "3.4.1",
    "endpointUrl": "https://hospital-1.example.org/fhir/messaging"
  },
  "responsible": { "reference": "Organization/hospital-1" },
  "reason": {
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/message-reasons-encounter",
      "code": "admit"
    }]
  },
  "focus": [{ "reference": "Encounter/example" }]
}

Common pitfalls

• MessageHeader not in first position — a Bundle type=message must have MessageHeader as entry[0].resource. Otherwise rejected.
• No source.endpointUrl — without a technical return URL, asynchronous acknowledgment is impossible.
• Untyped event[x] — the event code must be typed by a Coding or canonical MessageDefinition.
• Unresolvable focus — every Reference in focus must be present in the same Bundle.
• Mixing REST and messaging — the messaging pattern is asynchronous and event-driven. Don't use it for routine CRUD: prefer REST.

Related resources

• Bundle — mandatory type=message envelope.
• MessageDefinition — describes the event and expected content.
• OperationOutcome — error detail in response.details.
• HL7 v2 ADT^A01 — legacy pipe-delimited equivalent.