MedHook Documentation

MedHook is a self-hosted healthcare data integration platform. It moves data between EHRs, labs, payers, and internal systems using visual DAG workflows, typed adapters, and AI-assisted field mapping. PHI never leaves your infrastructure.

The platform ships as three independently deployable components:

A single Docker Compose command brings up the full engine stack: Next.js API, Postgres, Redis, Medplum, MLLP listener, Prometheus, and Grafana. Total time, with Docker already installed: under five minutes.

1. 1
   Sign in to medhook.dev and create a license key under Dashboard → API Keys.
2. 2
   Clone the engine repo, copy .env.example to .env, and fill in the three required secrets.
3. 3
   Run docker compose up -d, hit /api/health, and open the dashboard.

git clone https://github.com/medhook/engine.git
cd engine
cp .env.example .env

# Fill in the three required secrets:
#   ENCRYPTION_MASTER_KEY  (openssl rand -hex 32)
#   ENGINE_AUTH_SECRET     (openssl rand -hex 64)
#   LICENSE_KEY            (medhook.dev → Dashboard → API Keys)

docker compose up -d

# Verify
curl http://localhost:3000/api/health
# → { "status": "healthy" }

open http://localhost:3000

Every action in the engine is reachable through a REST API. JWT bearer tokens are obtained from /api/auth/token and expire after 2 hours. Pass the token in the Authorization: Bearer header on every other call.

# Exchange the engine auth secret for a 2-hour JWT
TOKEN=$(curl -s -X POST http://localhost:3000/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "secret": "'"$ENGINE_AUTH_SECRET"'",
    "licenseKey": "'"$LICENSE_KEY"'"
  }' | jq -r .token)

# Use it
curl http://localhost:3000/api/workflows \
  -H "Authorization: Bearer $TOKEN"

curl -X POST http://localhost:3000/api/adapter-profiles \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Epic FHIR Production",
    "adapterType": "fhir-rest",
    "config": {
      "baseUrl": "https://fhir.epic.com/api/FHIR/R4",
      "authType": "bearer",
      "credentials": { "token": "your-bearer-token" }
    }
  }'

The full reference (every route, request schema, and response shape) lives at docs/API.md in the engine repository.

Adapters are typed connectors — config validated by Zod, credentials encrypted with AES-256-GCM, connection-tested before use. Fourteen adapters ship in the box, covering EHRs, FHIR servers, REST APIs, file transfer, HL7v2, X12, and CDA.

Need a connector that isn't listed? The @medhook/adapter-sdk package lets you build out-of-tree adapters that plug into the engine without forking it.

Every integration in MedHook is a directed acyclic graph (DAG): a trigger fires, nodes execute, and edges connect them. Branching, parallel execution, and loops are all expressed as nodes — there is no separate orchestration layer.

Configuration for the engine lives in engine/.env. Three secrets must be set before first boot — everything else has a working default for local Docker Compose.

For production deployments, store the three required secrets in your platform's secrets manager (AWS Secrets Manager, Azure Key Vault, GCP Secret Manager) instead of a plaintext .env file.

Healthcare-grade defaults. PHI never leaves your infrastructure: medhook.dev only receives HMAC-signed aggregate analytics — never workflow data.

MedHook is fully self-hosted. The fastest path is Docker Compose for local and single-server deployments. Terraform templates exist for AWS, Azure, and GCP. A Helm chart and air-gap install are available for regulated environments.

# from the engine repo root
docker compose up -d

# tail logs
docker compose logs -f engine

# stop
docker compose down

cd engine/terraform/aws
terraform init
terraform apply

# Same pattern for Azure and GCP:
#   engine/terraform/azure
#   engine/terraform/gcp