Nov 20, 202612 min read

HL7 Message Ingestion Backend: MLLP, ACKs, Duplicates and ADT Events

Design the backend that receives HL7 v2 messages from hospital systems: an MLLP bridge in front of an HTTP endpoint, original-mode ACKs, duplicate control IDs, raw message storage, ADT events and a census that tolerates out-of-order delivery, then build it in Go with Encore.

Illustration for HL7 Message Ingestion Backend: MLLP, ACKs, Duplicates and ADT Events

Most hospital systems still send admits, transfers and discharges as HL7 v2 messages over MLLP, and expect an acknowledgment within seconds. A first receiver parses each message and writes a row.

Then a lost ACK brings a resend and a second admit, and a late discharge leaves a patient on the census. This guide designs ingestion that handles those cases, then builds it in Go with Encore.

HL7 ingestion at a glance

JobPatternWhy
TransportMLLP bridge in front of an HTTP endpointKeeps TCP framing out of the application
AcknowledgmentOriginal-mode ACK, AA, AE or ARTells the sender whether to resend
DuplicatesUnique on facility and MSH-10Senders resend on a lost ACK
Raw storageOriginal message in a private bucketReplay, audits and parser fixes
EventsADT topic, at-least-onceCensus, bed board and notifications subscribe
CensusApply only newer events per patientDelivery is not ordered

What does an HL7 v2 message look like?

An HL7 v2 message is a set of segments separated by carriage returns, each a list of fields separated by |, with components inside fields separated by ^. An admit looks like this:

MSH|^~\&|HISADT|STMARYS|CENSUS|ACME|20261120083000+0100||ADT^A01^ADT_A01|MSG00042|P|2.5.1 EVN|A01|20261120082955 PID|1||483920^^^STMARYS^MR||DOE^JANE||19800214|F PV1|1|I|4WEST^402^1

MSH is the header: sending application and facility in MSH-3 and MSH-4, the message time in MSH-7, the type ADT^A01 in MSH-9 and the control ID MSG00042 in MSH-10. PID-3 carries the medical record number and PV1-3 the ward, room and bed. Numbering is the first trap: in MSH, the field separator itself is MSH-1, so a naive split is off by one for that segment only.

Why put a bridge in front of MLLP?

MLLP wraps each message in a start byte 0x0B and ends it with 0x1C 0x0D on a long-lived TCP connection, usually over a VPN to the hospital. The sender writes one message and waits for the ACK before sending the next.

Running that listener inside the application couples your deploys to connections the hospital opens and rarely reopens gracefully. A thin bridge keeps the TCP side small and stable: it unwraps each message, POSTs it to the ingestion endpoint and writes the body of the response, the ACK, back over the connection. Teams use an integration engine channel for this or a short custom program. Google publishes an open source MLLP adapter, but it forwards to the Cloud Healthcare API HL7v2 store rather than to your own endpoint, as its setup guide shows. Mirth Connect, a common choice, became commercial-only with version 4.6 in March 2025, which is worth knowing before you pick it.

When should you send AA, AE or AR?

The ACK is a message too: an MSH back to the sender and an MSA segment with a code and the original control ID. In original acknowledgment mode the code is AA when you accepted the message, AE when something failed on your side and a resend may succeed, and AR when the message itself is unacceptable.

Get the split wrong and the sender behaves badly in both directions. Answering AR to a database timeout drops a message the hospital believes was rejected for content. Answering AE to an unsupported message type makes the sender retry forever and block every message behind it. Only acknowledge AA after the message is durably stored.

Duplicates and ordering

A sender that does not get an ACK in time resends with the same MSH-10, so store messages under a unique key of sending facility and control ID. A repeat of a message you already processed gets AA again and no second event. A repeat of one you stored but failed to publish should publish it, so track a status per message instead of treating "row exists" as "done".

Ordering needs the same care, because once events go through a queue with at-least-once delivery, a transfer can be processed after the discharge that followed it. Each consumer should compare the event time from MSH-7 with the last time applied for that patient and skip older events, which also makes redelivery harmless.

What to keep, and what to keep out of logs

Keep every original message unchanged in a private bucket keyed by facility, date and control ID. When the parser has a bug, or a downstream consumer needs a field you did not extract, you replay from storage instead of asking the hospital to resend a month of traffic.

These messages contain patient identifiers, names and dates of birth. Log control IDs and message types, not bodies, keep the bucket private, and restrict who can read it. Compliance obligations for that data stay with your organization and your agreements with the sending facility, whichever platform runs the code.

How do you build it with Encore?

Encore

Encore is a backend framework with built-in infrastructure, and here a Go service declares its database, a private object storage bucket for raw messages, a Pub/Sub topic for ADT events and a secret for the bridge token, and Encore provisions them in your AWS or GCP account. Encore services expose HTTP endpoints, so the MLLP bridge described above runs in front of the service.

Application code passes through Encore and infrastructure guardrails to resources provisioned in your own AWS or GCP account.
Encore provisions the infrastructure your application needs in your own AWS or GCP account.

Set up the app

Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

~
$ encore app create hl7-ingest --example=hello-world$ cd hl7-ingest && mkdir -p hl7/er7 hl7/migrations$ encore secret set --type prod,dev,local,pr BridgeToken

The migration creates the message log and the census:

-- hl7/migrations/1_create_tables.up.sql CREATE TABLE messages ( sending_facility TEXT NOT NULL, control_id TEXT NOT NULL, -- MSH-10 message_type TEXT NOT NULL, -- MSH-9, e.g. ADT^A01 raw_key TEXT NOT NULL, -- object key of the original message status TEXT NOT NULL DEFAULT 'received', -- received | published received_at TIMESTAMPTZ NOT NULL DEFAULT now(), PRIMARY KEY (sending_facility, control_id) ); CREATE TABLE encounters ( facility TEXT NOT NULL, patient_mrn TEXT NOT NULL, -- PID-3.1 location TEXT, -- PV1-3, NULL after discharge state TEXT NOT NULL, -- admitted | discharged last_event_at TIMESTAMPTZ NOT NULL, -- MSH-7 of the last applied event PRIMARY KEY (facility, patient_mrn) );

Reading ER7

A small reader covers the fields this service needs, with MSH shifted so that field numbers match the spec, and builds the ACK. A full parser library is worth it once you handle escape sequences and repeating fields, but the shape stays the same:

// hl7/er7/er7.go: a small HL7 v2 (ER7) reader for the fields this service uses. package er7 import ( "errors" "strings" "time" ) type Message struct { segments map[string][][]string // segment id -> occurrences -> fields } // Parse splits a message into segments (\r) and fields (|). // MSH is shifted so that Field("MSH", 9) returns MSH-9, as in the spec. func Parse(raw string) (*Message, error) { raw = strings.ReplaceAll(strings.TrimSpace(raw), "\n", "\r") if !strings.HasPrefix(raw, "MSH|") { return nil, errors.New("message does not start with MSH|") } m := &Message{segments: map[string][][]string{}} for _, seg := range strings.Split(raw, "\r") { if seg == "" { continue } fields := strings.Split(seg, "|") if fields[0] == "MSH" { fields = append([]string{"MSH", "|"}, fields[1:]...) } m.segments[fields[0]] = append(m.segments[fields[0]], fields) } return m, nil } // Field returns field n of the first occurrence of a segment, or "". func (m *Message) Field(seg string, n int) string { occ := m.segments[seg] if len(occ) == 0 || n >= len(occ[0]) { return "" } return occ[0][n] } // Component returns component c (1-based) of a field, split on ^. func (m *Message) Component(seg string, n, c int) string { parts := strings.Split(m.Field(seg, n), "^") if c-1 < len(parts) { return parts[c-1] } return "" } // Time parses an HL7 DTM such as 20261120083000 or 202611200830+0100. func Time(v string) (time.Time, error) { for _, layout := range []string{"20060102150405-0700", "200601021504-0700", "20060102150405", "200601021504", "20060102"} { if t, err := time.Parse(layout, v); err == nil { return t, nil } } return time.Time{}, errors.New("bad HL7 timestamp: " + v) } // Ack builds an original-mode acknowledgment for msg with code AA, AE or AR. func Ack(msg *Message, code, controlID string, now time.Time) string { msh := strings.Join([]string{ "MSH", "^~\\&", msg.Field("MSH", 5), msg.Field("MSH", 6), // our app and facility, from the receiver fields msg.Field("MSH", 3), msg.Field("MSH", 4), // back to the sender now.UTC().Format("20060102150405"), "", "ACK^" + msg.Component("MSH", 9, 2) + "^ACK", controlID, msg.Field("MSH", 11), msg.Field("MSH", 12), }, "|") return msh + "\rMSA|" + code + "|" + msg.Field("MSH", 10) + "\r" }

The ingestion endpoint

The raw endpoint checks the bridge token, stores the original, records the message under its control ID, publishes the ADT event and answers with the ACK. Each failure maps to AE or AR as described above:

// hl7/hl7.go package hl7 import ( "bytes" "context" "crypto/subtle" "fmt" "io" "net/http" "time" "encore.app/hl7/er7" "encore.dev/pubsub" "encore.dev/rlog" "encore.dev/storage/objects" "encore.dev/storage/sqldb" ) var secrets struct { BridgeToken string // shared with the MLLP bridge that forwards messages } var db = sqldb.NewDatabase("hl7", sqldb.DatabaseConfig{Migrations: "./migrations"}) // Original messages, kept unchanged for replay and audits. Private bucket. var Raw = objects.NewBucket("hl7-raw", objects.BucketConfig{Versioned: false}) type ADTEvent struct { Facility string `json:"facility"` ControlID string `json:"control_id"` Trigger string `json:"trigger"` // A01 admit, A02 transfer, A03 discharge, A08 update PatientMRN string `json:"patient_mrn"` Location string `json:"location"` OccurredAt time.Time `json:"occurred_at"` } var ADTEvents = pubsub.NewTopic[*ADTEvent]("adt-events", pubsub.TopicConfig{ DeliveryGuarantee: pubsub.AtLeastOnce, }) // Receive takes one ER7 message from the bridge and returns the HL7 ACK // the bridge relays to the sender over MLLP. // //encore:api public raw method=POST path=/hl7/messages func Receive(w http.ResponseWriter, req *http.Request) { token := req.Header.Get("X-Bridge-Token") if subtle.ConstantTimeCompare([]byte(token), []byte(secrets.BridgeToken)) != 1 { http.Error(w, "unauthorized", http.StatusUnauthorized) return } body, err := io.ReadAll(io.LimitReader(req.Body, 1<<20)) if err != nil { http.Error(w, "read error", http.StatusBadRequest) return } msg, err := er7.Parse(string(body)) if err != nil { http.Error(w, err.Error(), http.StatusBadRequest) // no MSH, nothing to ACK return } ack := func(code string) { w.Header().Set("Content-Type", "text/plain; charset=utf-8") io.WriteString(w, er7.Ack(msg, code, "ACK"+msg.Field("MSH", 10), time.Now())) } ctx := req.Context() facility, controlID := msg.Field("MSH", 4), msg.Field("MSH", 10) evt, err := toEvent(msg) if err != nil { rlog.Warn("rejecting message", "facility", facility, "control_id", controlID, "err", err) ack("AR") // the sender should not resend this unchanged return } // Store the original first, under a key derived from the control ID, // so a retry overwrites the same object instead of creating a new one. key := fmt.Sprintf("%s/%s/%s.hl7", facility, evt.OccurredAt.UTC().Format("2006/01/02"), controlID) wr := Raw.Upload(ctx, key, objects.WithUploadAttrs(objects.UploadAttrs{ContentType: "text/plain; charset=utf-8"})) if _, err := io.Copy(wr, bytes.NewReader(body)); err != nil { wr.Abort(err) ack("AE") return } if err := wr.Close(); err != nil { ack("AE") return } // Senders resend when an ACK is lost. A repeat of a published message is // acknowledged again without a second event. var status string err = db.QueryRow(ctx, ` INSERT INTO messages (sending_facility, control_id, message_type, raw_key) VALUES ($1, $2, $3, $4) ON CONFLICT (sending_facility, control_id) DO UPDATE SET raw_key = EXCLUDED.raw_key RETURNING status`, facility, controlID, msg.Field("MSH", 9), key).Scan(&status) if err != nil { ack("AE") return } if status == "published" { ack("AA") return } if _, err := ADTEvents.Publish(ctx, evt); err != nil { ack("AE") // the row stays 'received', so the resend publishes it return } if _, err := db.Exec(ctx, `UPDATE messages SET status = 'published' WHERE sending_facility = $1 AND control_id = $2`, facility, controlID); err != nil { rlog.Error("marking message published", "control_id", controlID, "err", err) } ack("AA") } func toEvent(msg *er7.Message) (*ADTEvent, error) { if msg.Component("MSH", 9, 1) != "ADT" { return nil, fmt.Errorf("unsupported message type %q", msg.Field("MSH", 9)) } occurred, err := er7.Time(msg.Field("MSH", 7)) if err != nil { return nil, err } mrn := msg.Component("PID", 3, 1) if mrn == "" || msg.Field("MSH", 10) == "" { return nil, fmt.Errorf("missing PID-3 or MSH-10") } return &ADTEvent{ Facility: msg.Field("MSH", 4), ControlID: msg.Field("MSH", 10), Trigger: msg.Component("MSH", 9, 2), PatientMRN: mrn, Location: msg.Component("PV1", 3, 1) + "-" + msg.Component("PV1", 3, 2), OccurredAt: occurred, }, nil } type CensusEntry struct { PatientMRN string `json:"patient_mrn"` Location string `json:"location"` } type CensusResponse struct { Patients []CensusEntry `json:"patients"` } // Census lists admitted patients at a facility. Private: other services only. // //encore:api private method=GET path=/hl7/census/:facility func Census(ctx context.Context, facility string) (*CensusResponse, error) { rows, err := db.Query(ctx, `SELECT patient_mrn, location FROM encounters WHERE facility = $1 AND state = 'admitted' ORDER BY location`, facility) if err != nil { return nil, err } defer rows.Close() out := &CensusResponse{} for rows.Next() { var e CensusEntry if err := rows.Scan(&e.PatientMRN, &e.Location); err != nil { return nil, err } out.Patients = append(out.Patients, e) } return out, rows.Err() }

The census subscription

The subscriber applies admits, transfers and discharges, and the WHERE clause on last_event_at drops any event older than the one already applied:

// hl7/census.go package hl7 import ( "context" "encore.dev/pubsub" ) var _ = pubsub.NewSubscription(ADTEvents, "update-census", pubsub.SubscriptionConfig[*ADTEvent]{ Handler: updateCensus, }) // updateCensus applies admits, transfers and discharges to the current census. // Delivery is at least once and not ordered, so each write only applies when // the event is newer than the last one applied for that patient. func updateCensus(ctx context.Context, e *ADTEvent) error { var state string var location *string switch e.Trigger { case "A01", "A02", "A08": state, location = "admitted", &e.Location case "A03": state = "discharged" default: return nil // other triggers are stored but do not change the census } _, err := db.Exec(ctx, ` INSERT INTO encounters (facility, patient_mrn, location, state, last_event_at) VALUES ($1, $2, $3, $4, $5) ON CONFLICT (facility, patient_mrn) DO UPDATE SET location = EXCLUDED.location, state = EXCLUDED.state, last_event_at = EXCLUDED.last_event_at WHERE encounters.last_event_at < EXCLUDED.last_event_at`, e.Facility, e.PatientMRN, location, state, e.OccurredAt) return err }

encore run starts a local Postgres, the bucket and the topic, so you can POST a sample message with the token header and get an ACK back. The reader has plain Go tests that run with go test ./hl7/er7, and the service tests run under encore test. On deploy, the database runs on RDS or Cloud SQL, the bucket on S3 or Cloud Storage and the topic on SNS and SQS or GCP Pub/Sub, and Encore provisions an IAM role for the service.

A coding agent adding a bed-board service subscribes to adt-events in Go and runs both services locally in the same change, without provisioning a queue or granting access to it in a separate step.

How would you build it by hand?

On AWS the same design is an ECS service behind an internal load balancer, an RDS Postgres database, a private S3 bucket with a bucket policy for the service's task role, an SNS topic with an SQS queue and dead-letter queue per consumer, and a Secrets Manager secret for the bridge token, all defined in Terraform. On GCP it maps to Cloud Run, Cloud SQL, Cloud Storage and Pub/Sub. The application code is close to the Go above with the SDK calls swapped in, and most of the extra work is the IAM, networking and queue configuration around it.

Things to decide early

  • Which message types you accept. Answer AR to the rest and keep them in raw storage so you can add support later without asking for a resend.
  • The identity key for patients. PID-3 can repeat with identifiers from several authorities, so pick the assigning authority you trust per facility.
  • Retention for raw messages. Set a lifecycle rule that matches your agreements with the sending facility.
  • Who reads raw messages. Keep the bucket private and grant read access to a support role, not to every service.

Frequently asked questions

How do you receive HL7 v2 messages in a modern backend?

Hospital systems send HL7 v2 over MLLP, a TCP framing with a start byte and two end bytes. Run an MLLP listener as a thin bridge that unwraps each message, POSTs it to an HTTP endpoint and writes the HL7 ACK from the response back over the connection. The application logic then lives behind ordinary HTTP.

What is the difference between AA, AE and AR in an HL7 ACK?

In original acknowledgment mode, MSA-1 is AA when the receiver accepted the message, AE when it hit an error and the sender may retry, and AR when it rejected the message, for example an unsupported type or a missing required field, which the sender should not resend unchanged.

How do you handle duplicate HL7 messages?

Senders resend when they do not get an ACK in time, with the same MSH-10 control ID. Store messages under a unique key of sending facility and control ID, acknowledge a repeat with AA, and only publish downstream events for the first copy.

How do you build HL7 ingestion with Encore?

With Encore, declare the database, a private bucket for raw messages, an ADT event topic and a secret for the bridge token in Go. A raw endpoint parses, stores and acknowledges each message, a subscription updates the census, and deploys provision the database, bucket and topic in your own AWS or GCP account.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders