HL7 Transport: HL7 over HTTPS/REST

HL7 over HTTPS (HTTP Secure) carries HL7 v2 and FHIR messages inside HTTP POST requests and responses, using TLS encryption for confidentiality and integrity. A client sends an HL7 message as the HTTP request body; the receiver responds with an HL7 ACK or FHIR response in the HTTP response body. This transport unifies healthcare data exchange with standard web infrastructure, firewalls, load balancers, and monitoring tools.

What is HL7 over HTTPS

HL7 over HTTPS is a synchronous, request-response transport that wraps HL7 v2 or FHIR messages in HTTP requests and responses. The sender is the HTTP client; the receiver is the HTTP server. The message—whether an HL7 ADT, ORM, ORU, or a FHIR Bundle—becomes the body of an HTTP POST request, and the receiver's ACK or response is returned in the HTTP response body. The transport layer is HTTP/1.1 (RFC 7230) with TLS encryption (HTTPS, port 443 in production), making it compatible with standard web infrastructure: reverse proxies, load balancers, web application firewalls, and API gateways.

Unlike raw TCP (MLLP, port 6660), HTTPS integrates with existing IT security controls: TLS certificate validation, HTTP authentication (OAuth2, API keys, mutual TLS), and web-standard logging and monitoring. The synchronous nature ensures that the sender receives a response before moving to the next message, simplifying acknowledgment tracking and error handling.

How it works

The client initiates a TLS handshake to establish an encrypted connection to the receiver's endpoint (e.g., https://ehr.hospital.org/hl7/messages). Once the TLS tunnel is open, the client constructs an HTTP POST request with:

Request line: POST /hl7/messages HTTP/1.1
Headers: Content-Type: application/fhir+json (or application/hl7-v2, depending on format), Content-Length, Authorization (if required), and optional Accept
Body: The complete HL7 v2 message (ER7 format: pipe-delimited segments) or FHIR resource as JSON or XML

The receiver parses the message, validates it, processes it, and returns an HTTP response with:

Status line: HTTP/1.1 200 OK (or appropriate 2xx/4xx/5xx status)
Headers: Content-Type, Content-Length, and other metadata
Body: The HL7 ACK message (MSA segment) or FHIR response Bundle

The connection then closes or remains open for HTTP keep-alive pipelining (if configured). The synchronous round-trip ensures both parties confirm receipt and processing.

Client                                          Server
  |                                               |
  |-- TLS Handshake --------------------------->  |
  |<-- TLS Handshake Complete ------------------|
  |                                               |
  |-- HTTP POST /hl7/messages --------->  |
  |    Content-Type: application/hl7-v2  |
  |    Content-Length: 512                |
  |                                        |
  |    MSH|^~&|SENDER|FACILITY|...      |
  |    PID|1||MRN123^^^FACILITY|...       |
  |    OBR|1|ORDER123|LAB001|...          |
  |                                        |
  |<-- HTTP/1.1 200 OK --------- <--------|
  |    Content-Type: application/hl7-v2   |
  |    Content-Length: 128                |
  |                                        |
  |    MSH|^~&|RECEIVER|FACILITY|...    |
  |    MSA|AA|MSG001|...                  |
  |                                        |
  |-- [TLS close or keep-alive] -------->  |
  |                                        |

When to use it

HL7 over HTTPS is the right choice when:

Cloud and hybrid environments: The endpoint is behind a web proxy, API gateway, or load balancer in a cloud or hybrid IT architecture.
RESTful integration: Your team is building modern APIs and wants to use HTTP verbs, status codes, and standard REST patterns instead of raw TCP.
Web security tools: Your organization runs web application firewalls (WAF), intrusion detection, or TLS inspection that only understand HTTP.
Synchronous workflows: The sender must know immediately whether the message was accepted or rejected before proceeding (e.g., urgent lab result confirmation).
Multi-tenancy and routing: You need URL-based routing (e.g., /hospital/lab vs. /hospital/pharmacy) to direct messages to different backends.
OAuth2 or API-key authentication: Your security policy requires modern HTTP authentication instead of IP allowlists or MLLP credentials.
Public internet: You need to exchange data with external partners over untrusted networks; TLS and HTTP authentication provide strong boundaries.

Avoid HL7 over HTTPS if:

High-frequency, asynchronous bulk loads: The round-trip latency of waiting for HTTP responses will overwhelm a busy inbound queue. Use file-drop or batch MLLP instead.
Legacy MLLP-only infrastructure: Your existing systems only speak MLLP, and bridging costs exceed the benefit of modernization.
Firewall blocking HTTP: Your partner's network only allows file-share or SFTP, not outbound HTTPS.

Configuration parameters

Parameter	Value	Notes
Protocol	HTTPS (TLS 1.2 or 1.3 recommended)	HTTP may be used in development, but production must use HTTPS (TLS).
Port	443 (standard HTTPS)	May vary; check with receiver for custom ports (e.g., 8443).
Method	HTTP POST	PUT, PATCH, or GET for specific use cases, but POST is standard for message submission.
Content-Type	`application/fhir+json`, `application/fhir+xml`, `application/hl7-v2`	Depends on message format. FHIR R4+: `application/fhir+json`; HL7 v2 ER7: `application/hl7-v2` (IANA registered).
Character Encoding	UTF-8	FHIR and HL7 v2 mandate UTF-8 (ISO 8859-1 legacy is not recommended).
HTTP Version	1.1 or 2.0	HTTP/1.1 is universal; HTTP/2 is supported by modern servers and reduces latency.
Timeout	30–120 seconds	Receiver processing time; set per interface. Typical acknowledgment should arrive within 5–10 seconds.
Compression	gzip (optional)	`Content-Encoding: gzip` reduces payload size for large batch messages.
Keep-Alive	`Connection: keep-alive` (optional)	Reuses TLS connection for multiple messages, reducing handshake overhead.
Authentication	TLS certificate, OAuth2 Bearer token, API key, or HTTP Basic	Specific mechanism agreed with receiver.
Certificate Validation	Required	Verify receiver's TLS certificate is signed by a trusted CA; reject self-signed in production.

Security

TLS Encryption: TLS 1.2 (minimum; 1.3 preferred) encrypts all data in flight, preventing eavesdropping. Both client and server must perform certificate validation: the client verifies the server's certificate chain; the server may validate the client certificate (mutual TLS) if configured.

Authentication: Common patterns include:

Mutual TLS (mTLS): Both client and server present certificates; used in B2B healthcare exchanges (e.g., between EHR systems).
OAuth2 Bearer Token: Client includes a JWT or opaque token in the Authorization: Bearer <token> header; receiver validates the token with an authorization server.
API Key: Client includes Authorization: ApiKey <key> or a custom header; receiver looks up the key in its key store.
HTTP Basic Auth: Username and password in Authorization: Basic <base64> (only over HTTPS; never over plain HTTP).

Message Integrity: TLS provides cryptographic proof that the message was not tampered with in transit. For additional application-level integrity, include a digital signature or HMAC in the HL7/FHIR payload.

Audit Logging: HTTP servers log all requests and responses (method, URI, status code, timestamp). Use these logs for compliance and troubleshooting. Avoid logging sensitive fields (e.g., patient names) at the HTTP level; instead, redact them before logging.

Pros & cons

Pros:

Standards-aligned: Uses RFC 7230 (HTTP), RFC 5246 (TLS), and IANA media types. Widely understood by web and API teams.
Firewall-friendly: HTTPS on port 443 is allowed by nearly all enterprise firewalls and proxies. Works through NAT and proxies.
Modern authentication: Integrates with OAuth2, JWT, and mutual TLS—the standard for cloud and SaaS platforms.
Observability: HTTP status codes, response times, and error bodies make debugging straightforward. Works with standard monitoring and logging tools (e.g., ELK, Splunk).
Synchronous feedback: Sender knows immediately if the message was accepted (200 OK) or rejected (4xx, 5xx) and can handle errors in real-time.
Multi-tenancy: URL-based routing and query parameters allow a single endpoint to serve many organizations or departments.
Load balancing: HTTP/HTTPS work seamlessly with Layer 7 (application-layer) load balancers, API gateways, and reverse proxies (e.g., Nginx, AWS ALB).
RESTful idempotency: Idempotency keys and status codes make it safe to retry messages without duplicates.

Cons:

Synchronous overhead: Sender must wait for the receiver to process and respond. For high-volume inbound queues, this can become a bottleneck if the receiver is slow.
TLS/certificate management: Requires valid certificates, CA chains, and periodic renewal. Expired or misconfigured certificates cause outages.
HTTP stack complexity: Debugging HTTP/TLS requires familiarity with sockets, encryption, and protocol details. More complex than raw TCP (MLLP) in embedded systems.
Not truly asynchronous: Unlike file-drop or message queues, there is no natural way to queue and retry failed messages. 5xx errors must be retried at the client level.
Payload size: Each message incurs HTTP header overhead (~200–500 bytes); not significant for HL7, but adds up for batches.
Stateless: Each HTTP request is independent; there is no persistent session or connection state visible to the application (though TLS and keep-alive do reuse the TCP connection).

Examples

Example 1: Wire-level HTTP POST request and response

Client sends an HL7 ADT message over HTTPS:

POST /hl7/receive HTTP/1.1
Host: ehr.hospital.org
Content-Type: application/hl7-v2
Content-Length: 527
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/hl7-v2
User-Agent: Vorro-HL7-Client/1.0

MSH|^~&|REGMGR|HOSPITAL|HL7RECV|HOSPITAL|20260701120000||ADT^A01^ADT_A01|MSG000123|P|2.5.1
EVN|A01|20260701120000|||SYSTEM
PID|1||MRN123456^^^HOSPITAL~12345^^^NPI||Doe^Jane^M||19800615|F|||123 Main St^^Chicago^IL^60601^USA||^^^^^(312)555-0123|^^^^^(312)555-0124||S|C|||||||||||||||||N
NK1|1|Doe^John|SPO|123 Main St^^Chicago^IL^60601||^^^^^(312)555-0199
PV1|1|I|CARDIO^ICU^BED01^A|H|||001234^Smith^John^Dr.||CAR|||N||||2|||001234^Smith^John^Dr.|||||||||||||||||||20260701100000

Server responds with an HL7 acknowledgment (ACK):

HTTP/1.1 200 OK
Content-Type: application/hl7-v2
Content-Length: 129
Date: Wed, 01 Jul 2026 12:00:01 GMT
Server: Vorro-HL7-Server/1.0
Connection: keep-alive

MSH|^~&|HL7RECV|HOSPITAL|REGMGR|HOSPITAL|20260701120000||ACK^A01^ACK|MSG000123|P|2.5.1
MSA|AA|MSG000123|Patient admitted successfully

Example 2: Annotated HTTP request with FHIR Bundle (JSON)

A FHIR-based HTTP request carrying a message Bundle:

POST /fhir/Bundle HTTP/1.1
Host: ehr.hospital.org
Content-Type: application/fhir+json
Content-Length: 2048
Authorization: Bearer <OAuth2-token>

{
  "resourceType": "Bundle",
  "type": "message",
  "entry": [
    {
      "resource": {
        "resourceType": "MessageHeader",
        "id": "messageheader-001",
        "eventCoding": {
          "system": "http://terminology.hl7.org/CodeSystem/v2-0003",
          "code": "A01",
          "display": "Admit/Visit Notification"
        },
        "sender": {
          "reference": "Organization/REGMGR"
        },
        "focus": [
          {
            "reference": "Patient/pat123"
          }
        ]
      }
    },
    {
      "resource": {
        "resourceType": "Patient",
        "id": "pat123",
        "identifier": [
          {
            "system": "urn:oid:1.2.840.113619.6.21",
            "value": "MRN123456"
          }
        ],
        "name": [
          {
            "use": "official",
            "family": "Doe",
            "given": ["Jane"]
          }
        ],
        "birthDate": "1980-06-15"
      }
    }
  ]
}

Server responds with a FHIR Bundle of type message-response:

HTTP/1.1 200 OK
Content-Type: application/fhir+json
Content-Length: 512

{
  "resourceType": "Bundle",
  "type": "message-response",
  "entry": [
    {
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [
          {
            "severity": "information",
            "code": "informational",
            "details": {
              "text": "Patient admitted successfully"
            }
          }
        ]
      }
    }
  ]
}

Example 3: Sample NextGen Connect (Mirth) HTTP listener configuration

A Mirth HTTP listener connector receiving HL7 messages:

<!-- Mirth HTTP Listener Channel -->
<channel name="HL7-HTTPS-Receiver" enabled="true">
  <sourceConnector>
    <name>HTTP Listener</name>
    <properties>
      <listenerConnectorProperties>
        <host>0.0.0.0</host>
        <port>8443</port>
        <ssl>true</ssl>
        <sslProtocol>TLSv1.2</sslProtocol>
        <keyStore>/etc/mirth/keystore.jks</keyStore>
        <keyStorePassword>changeme</keyStorePassword>
        <responseContentType>application/hl7-v2</responseContentType>
        <responseBodyCharset>UTF-8</responseBodyCharset>
        <timeout>60</timeout>
      </listenerConnectorProperties>
    </properties>
  </sourceConnector>
  
  <destinationConnector>
    <name>HTTP Sender (ACK)</name>
    <properties>
      <httpSenderProperties>
        <url>${hl7AckEndpoint}</url>
        <method>POST</method>
        <headers>
          <header>
            <name>Content-Type</name>
            <value>application/hl7-v2</value>
          </header>
          <header>
            <name>Authorization</name>
            <value>Bearer ${oauth2Token}</value>
          </header>
        </headers>
        <timeout>30</timeout>
      </httpSenderProperties>
    </properties>
  </destinationConnector>
</channel>

Example 4: Failure-mode error response

Client sends a malformed message; server responds with an HTTP error:

POST /hl7/receive HTTP/1.1
Host: ehr.hospital.org
Content-Type: application/hl7-v2
Content-Length: 150
Authorization: Bearer <token>

MSH|^~&|REGMGR|HOSPITAL
PID|1||MRN123|...
OBX|1|CE|12345||INVALID|||F

Server responds with 400 Bad Request:

HTTP/1.1 400 Bad Request
Content-Type: application/hl7-v2
Content-Length: 200

MSH|^~&|HL7RECV|HOSPITAL|REGMGR|HOSPITAL|20260701120002||ACK^A01^ACK|MSG000124|P|2.5.1
MSA|AE|MSG000124|Segment count mismatch: expected at least 4, got 3
ERR|PID|3||||101^Required field missing^HL70357

Server error log:

[2026-07-01 12:00:02.456] ERROR [HTTP-HL7-Receiver] Parsing failed for message MSG000124 from 192.0.2.10:
  ca.uhn.hl7v2.HL7Exception: Unexpected end of message (segment PID missing required fields)
    at ca.uhn.hl7v2.parser.GenericParser.parse(GenericParser.java:123)
    at com.vorro.hl7.HttpListenerServlet.doPost(HttpListenerServlet.java:89)
  Message body: "MSH|^~&|REGMGR|HOSPITALnPID|1||MRN123|..."

Vorro support for HL7 over HTTPS

Vorro's HL7 engine natively supports HL7 over HTTPS via the HTTP/REST transport module. When receiving, Vorro listens on a configurable port (default 8443 or 443 behind a reverse proxy) and accepts POST requests with application/hl7-v2 or application/fhir+json content. The message is parsed, validated, and passed through Vorro's transformation pipeline. Responses are constructed as HL7 ACKs or FHIR OperationOutcome resources and returned with appropriate HTTP status codes (200, 400, 500).

When sending, Vorro uses the HTTP/REST sender to POST messages to external endpoints. The sender supports OAuth2 Bearer tokens, API keys, mutual TLS, and custom headers. Vorro tracks the HTTP response status; 200 OK is recorded as success, while 4xx and 5xx trigger retry logic with exponential backoff (default 1s, 5s, 30s, 5m).

Vorro can also act as a reverse proxy or API gateway for legacy MLLP systems: it listens on HTTPS and proxies to backend MLLP servers, transparently converting between HTTP and MLLP transport layers.

Sources

← Back to HL7 v2 Guide