{
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "agent": "light",
  "timestamp": "2025-01-19T12:00:00.000Z",
  "sequenceNumber": 7,
  "result": {
    "selectedElements": [
      {
        "item": "Hemoglobin A1c",
        "category": "Laboratory Value",
        "patient_value": "7.2%",
        "matching_reason": "Elevated HbA1c indicates suboptimal glycemic control"
      }
    ],
    "patientResponse": "Your recent lab results show elevated blood sugar levels...",
    "clinicianResponse": "The patient presents with elevated HbA1c (7.2%) indicating...",
    "citations": {
      "patient": {
        "1": {
          "url": "https://pubmed.ncbi.nlm.nih.gov/12345678/",
          "title": "Glycemic Control in Type 2 Diabetes",
          "metadata": {
            "type": "pubmed"
          }
        },
        "2": {
          "url": "https://doi.org/10.2337/dc24-S006",
          "title": "ADA Standards of Care in Diabetes — Glycemic Goals and Hypoglycemia",
          "metadata": {
            "type": "guideline",
            "source": "ADA",
            "author": "American Diabetes Association",
            "doi": "10.2337/dc24-S006",
            "pubdate": "2024-01-01",
            "abstract_snippet": "Glycemic management is primarily assessed with the A1C test, which reflects average glycemia over approximately 2-3 months...",
            "specialties": [
              "Endocrinology"
            ]
          }
        }
      },
      "clinician": {
        "1": {
          "url": "https://pubmed.ncbi.nlm.nih.gov/87654321/",
          "title": "ADA Standards of Care 2025",
          "metadata": {
            "type": "pubmed"
          }
        },
        "2": {
          "url": "https://doi.org/10.2337/dc24-S009",
          "title": "ADA Standards of Care — Pharmacologic Approaches to Glycemic Treatment",
          "metadata": {
            "type": "guideline",
            "source": "ADA",
            "author": "American Diabetes Association",
            "doi": "10.2337/dc24-S009",
            "pubdate": "2024-01-01",
            "abstract_snippet": "A patient-centered approach should guide the choice of pharmacologic agents...",
            "specialties": [
              "Endocrinology"
            ]
          }
        }
      }
    }
  }
}

API Reference

Ehr agent webhook

Sent to your webhook URL when EHR Agent analysis is complete (success or error).

Webhook Delivery:

Webhooks are delivered via HTTP POST to the webhookUrl you provide in your request
We retry failed deliveries up to 3 times with exponential backoff (immediate, 5s, 15s delays)
Your endpoint should return a 2xx status code within 30 seconds to acknowledge receipt
If all retries fail, the webhook is logged but not redelivered

Webhook Security: All webhooks are signed with HMAC-SHA256 using your company’s webhook secret. You must verify the signature to ensure authenticity.

Webhook Headers:

X-Helios-Signature: HMAC-SHA256 signature in format sha256=<hex>
X-Helios-Timestamp: Unix timestamp (seconds) when webhook was sent
X-Helios-Run-ID: The unique run ID for this analysis

Signature Verification:

Get the raw request body (as string, before JSON parsing)
Check timestamp is recent (within 5 minutes) to prevent replay attacks
Compute expected signature: sha256=HMAC-SHA256(webhook_secret, raw_body)
Compare signatures using timing-safe comparison

Example Verification (Node.js):

import { createHmac, timingSafeEqual } from 'crypto'

function verifyWebhook(rawBody: string, signature: string, timestamp: string, webhookSecret: string): boolean {
  // Check timestamp is recent (within 5 minutes)
  const now = Math.floor(Date.now() / 1000)
  const webhookTime = parseInt(timestamp, 10)
  if (Math.abs(now - webhookTime) > 300) {
    return false
  }

  // Compute expected signature
  const expected = 'sha256=' + createHmac('sha256', webhookSecret)
    .update(rawBody)
    .digest('hex')

  // Timing-safe comparison
  if (expected.length !== signature.length) return false
  return timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
}

See full documentation at: https://docs.heliosai.health/webhooks

{
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "agent": "light",
  "timestamp": "2025-01-19T12:00:00.000Z",
  "sequenceNumber": 7,
  "result": {
    "selectedElements": [
      {
        "item": "Hemoglobin A1c",
        "category": "Laboratory Value",
        "patient_value": "7.2%",
        "matching_reason": "Elevated HbA1c indicates suboptimal glycemic control"
      }
    ],
    "patientResponse": "Your recent lab results show elevated blood sugar levels...",
    "clinicianResponse": "The patient presents with elevated HbA1c (7.2%) indicating...",
    "citations": {
      "patient": {
        "1": {
          "url": "https://pubmed.ncbi.nlm.nih.gov/12345678/",
          "title": "Glycemic Control in Type 2 Diabetes",
          "metadata": {
            "type": "pubmed"
          }
        },
        "2": {
          "url": "https://doi.org/10.2337/dc24-S006",
          "title": "ADA Standards of Care in Diabetes — Glycemic Goals and Hypoglycemia",
          "metadata": {
            "type": "guideline",
            "source": "ADA",
            "author": "American Diabetes Association",
            "doi": "10.2337/dc24-S006",
            "pubdate": "2024-01-01",
            "abstract_snippet": "Glycemic management is primarily assessed with the A1C test, which reflects average glycemia over approximately 2-3 months...",
            "specialties": [
              "Endocrinology"
            ]
          }
        }
      },
      "clinician": {
        "1": {
          "url": "https://pubmed.ncbi.nlm.nih.gov/87654321/",
          "title": "ADA Standards of Care 2025",
          "metadata": {
            "type": "pubmed"
          }
        },
        "2": {
          "url": "https://doi.org/10.2337/dc24-S009",
          "title": "ADA Standards of Care — Pharmacologic Approaches to Glycemic Treatment",
          "metadata": {
            "type": "guideline",
            "source": "ADA",
            "author": "American Diabetes Association",
            "doi": "10.2337/dc24-S009",
            "pubdate": "2024-01-01",
            "abstract_snippet": "A patient-centered approach should guide the choice of pharmacologic agents...",
            "specialties": [
              "Endocrinology"
            ]
          }
        }
      }
    }
  }
}

Authorizations

x-api-key

string

header

required

API key provided by Helios Intelligence

Body

application/json

Option 1
Option 2

runId

string<uuid>

required

Unique identifier for this analysis run

status

enum<string>

required

Indicates successful completion

Available options:

completed

timestamp

string<date-time>

required

ISO 8601 timestamp when the webhook was sent

sequenceNumber

integer

required

Monotonically increasing number for ordering webhooks

Example:

7

result

object

required

Show child attributes

agent

enum<string>

The agent type that processed this request

Available options:

light,

deep

Response

200

Webhook received successfully. Return 200 OK to acknowledge receipt.

POST /api/v1/lab-results Lab results agent webhook