Webhooks - HANA

Overview

Webhooks are how HANA pushes data to your system in real time. When a patient interaction completes, a risk flag is detected, or a clinical note is generated, HANA sends an HTTP POST to your configured endpoint. This is the primary mechanism for the “closed loop” — HANA engages the patient, then sends structured results back to your EHR, care platform, or internal system.

Event Types

Engagement Events

Event	Fired When	Typical Use
`engagement.scheduled`	Engagement queued for future delivery	Update your scheduling UI
`engagement.started`	Patient answered (voice) or responded (SMS)	Log interaction start
`engagement.completed`	Full interaction finished	Ingest clinical note, update EHR
`engagement.failed`	Could not reach patient after retries	Trigger manual follow-up
`engagement.cancelled`	Engagement cancelled via API	Clean up internal records

Clinical Events

Event	Fired When	Typical Use
`engagement.escalated`	Risk signal detected during conversation	Alert care team immediately
`engagement.task_created`	Clinical task generated from interaction	Route to task queue
`clinical_note.ready`	Structured clinical note finalized	Write to EHR

Patient Events

Event	Fired When	Typical Use
`patient.memory_updated`	Patient preferences or patterns learned	Sync longitudinal profile
`patient.barrier_detected`	New adherence barrier identified	Update care plan
`patient.trend_change`	Significant change in tracked metric	Notify provider

System Events

Event	Fired When	Typical Use
`system.health`	Periodic health check	Monitoring dashboards
`batch.completed`	Batch engagement job finished	Process bulk results

Payload Structure

Every webhook payload follows a consistent envelope:

{
  "id": "evt_abc123",
  "event": "engagement.completed",
  "timestamp": "2026-02-08T10:08:30Z",
  "api_version": "2026-01-01",
  "data": {
    // Event-specific payload
  }
}

`engagement.completed` Payload

The most common event. Contains the full output of a patient interaction:

{
  "id": "evt_abc123",
  "event": "engagement.completed",
  "timestamp": "2026-02-08T10:08:30Z",
  "api_version": "2026-01-01",
  "data": {
    "engagement_id": "eng_abc123",
    "patient_id": "P-12345",
    "protocol": "medication-adherence-diabetes",
    "channel": "voice",
    "duration_seconds": 390,
    "clinical_note": {
      "summary": "Patient reports taking metformin ~4/7 days this week. Primary barrier is cost — insurance changed and copay increased. Reports mild nausea but considers it tolerable. No other side effects. Mood stable, sleep adequate.",
      "structured_data": {
        "medication_adherence": 0.57,
        "barriers": ["cost"],
        "side_effects": ["mild_nausea"],
        "mood": "stable",
        "sdoh_flags": ["insurance_change"]
      }
    },
    "tasks": [
      {
        "id": "task_xyz",
        "type": "review_medication_assistance",
        "priority": "medium",
        "reason": "Patient reports cost barrier to adherence due to insurance change",
        "suggested_action": "Review copay assistance programs or generic alternatives"
      }
    ],
    "risk_flags": [],
    "risk_level": "low",
    "metrics": {
      "engagement_score": 0.92,
      "completion_rate": 1.0,
      "interaction_count": 8,
      "sentiment": "neutral_positive"
    },
    "transcript_url": "https://api.hana.health/v1/engagements/eng_abc123/transcript"
  }
}

`engagement.escalated` Payload

Sent immediately when a risk signal is detected. This is the highest-priority event:

{
  "id": "evt_esc456",
  "event": "engagement.escalated",
  "timestamp": "2026-02-08T10:05:12Z",
  "api_version": "2026-01-01",
  "data": {
    "engagement_id": "eng_abc123",
    "patient_id": "P-12345",
    "escalation_type": "clinical_risk",
    "severity": "high",
    "reason": "Patient expressed passive suicidal ideation during medication discussion",
    "action_taken": "AI conversation paused. Patient informed of crisis resources.",
    "requires_human_review": true,
    "contact_info": {
      "phone": "+15550123456",
      "last_channel": "voice"
    }
  }
}

Escalation events should trigger immediate action in your system. Configure alerts, page on-call staff, or route to a human operator. HANA pauses the AI conversation and follows the clinic’s defined escalation protocol, but your system must acknowledge and act.

Configuring Webhooks

Via API

POST /v1/webhooks

{
  "url": "https://your-app.com/webhooks/hana",
  "events": [
    "engagement.completed",
    "engagement.escalated",
    "clinical_note.ready"
  ],
  "secret": "whsec_your_secret_here"
}

Via SDK

await hana.webhooks.create({
  url: 'https://your-app.com/webhooks/hana',
  events: ['engagement.completed', 'engagement.escalated'],
  secret: process.env.HANA_WEBHOOK_SECRET
});

hana.webhooks.create(
    url="https://your-app.com/webhooks/hana",
    events=["engagement.completed", "engagement.escalated"],
    secret=os.environ["HANA_WEBHOOK_SECRET"]
)

Filtering Events

Subscribe only to the events you need. Less noise, fewer wasted requests:

{
  "url": "https://your-ehr.com/hana-notes",
  "events": ["clinical_note.ready"],
  "filters": {
    "protocol": ["medication-adherence-*", "intake-*"],
    "risk_level": ["medium", "high", "critical"]
  }
}

Delivery & Retry

HANA guarantees at-least-once delivery for all webhook events.

Retry Schedule

If your endpoint returns a non-2xx status code or times out (30 seconds), HANA retries with exponential backoff:

Attempt	Delay
1st retry	30 seconds
2nd retry	2 minutes
3rd retry	10 minutes
4th retry	1 hour
5th retry	4 hours

After 5 failed attempts, the event is moved to the dead letter queue. You can replay failed events via the API:

POST /v1/webhooks/{webhook_id}/replay

{
  "event_ids": ["evt_abc123", "evt_def456"]
}

Idempotency

Every event has a unique id. Your system should deduplicate based on this ID, since retries may deliver the same event more than once.

// Example: Check if event was already processed
const processed = await db.webhookEvents.findOne({ eventId: event.id });
if (processed) return res.status(200).send('already processed');

Testing Webhooks

Sandbox Events

In sandbox mode, all engagements produce simulated webhook events. Test your integration end-to-end without real patient calls:

const hana = new HanaClient({
  apiKey: process.env.HANA_API_KEY,
  environment: 'sandbox'
});

// This triggers a simulated engagement + webhook delivery
const engagement = await hana.engagements.create({
  patient: { id: 'TEST-001', phone: '+15550000000' },
  protocol: 'medication-adherence-diabetes',
  triggerType: 'immediate'
});

Manual Event Trigger

Send a test event to your endpoint:

POST /v1/webhooks/{webhook_id}/test

{
  "event": "engagement.completed"
}

This sends a synthetic payload to your URL so you can verify connectivity, parsing, and signature verification.

Next: EHR Integration

Connect HANA to your Electronic Health Record system.

​Overview

​Event Types

​Engagement Events

​Clinical Events

​Patient Events

​System Events

​Payload Structure

​engagement.completed Payload

​engagement.escalated Payload

​Configuring Webhooks

​Via API

​Via SDK

​Filtering Events

​Delivery & Retry

​Retry Schedule

​Idempotency

​Testing Webhooks

​Sandbox Events

​Manual Event Trigger

Next: EHR Integration

Overview

Event Types

Engagement Events

Clinical Events

Patient Events

System Events

Payload Structure

`engagement.completed` Payload

`engagement.escalated` Payload

Configuring Webhooks

Via API

Via SDK

Filtering Events

Delivery & Retry

Retry Schedule

Idempotency

Testing Webhooks

Sandbox Events

Manual Event Trigger