Skip to content
HAMI Integration Platform

Intake Summary Webhook

Overview

Section titled “Overview”

The Intake Summary Webhook enables your healthcare facility to automatically receive AI-generated patient summaries from HAMI as patients complete their intake sessions. HAMI will POST structured summary data to your designated endpoint in real-time, ensuring your system always has the latest patient information without requiring manual data retrieval.

This push-based integration provides real-time updates and progressive enhancement as patients interact with HAMI multiple times.

Authentication

Section titled “Authentication”

Your endpoint must validate incoming requests using API key authentication in the request headers.

X-API-Key: your_api_key_here

Endpoint Requirements

Section titled “Endpoint Requirements”

Your Endpoint URL: https://your-facility-api.com/api/ai-summary

Method: POST

Content-Type: application/json

Requirements:

  • Must be publicly accessible via HTTPS
  • Must validate the X-API-Key header
  • Must respond within 15 seconds. HAMI treats slower responses as failed.
  • Must handle repeat deliveries: if an intake summary is regenerated, HAMI posts the updated summary for the same appointmentId again
  • HAMI does not retry a failed delivery automatically. Keep your endpoint highly available, and contact support if a summary needs to be re-sent.

Request Schema

Section titled “Request Schema”

Headers

Section titled “Headers”
HeaderTypeRequiredDescription
X-API-KeystringYesYour facility’s API authentication key (provided to HAMI)
Content-TypestringYesAlways application/json

Request Body

Section titled “Request Body”

HAMI will POST a JSON payload containing appointment information, patient demographics, and the AI-generated intake summary.

Payload Structure

Section titled “Payload Structure”
{
  appointmentId: string;           // HAMI appointment identifier
  transactionId?: string;          // transactionId returned by the Universal Ingestion API
  dateCreated: string;             // Timestamp when the summary was generated (UTC by default)
  emergency_patient: boolean;      // true if HAMI flagged the patient as a possible emergency during intake
  sourcePatientId?: string;        // fullUrl of the Patient entry in your ingested bundle
  sourceappointmentId?: string;    // fullUrl of the Appointment entry in your ingested bundle
  intakeSummary: {
    "Patient Information": {
      "Date of Birth/Age": string;
      "Gender": string;
    };
    "Chief Complaint": string;
    "History of Present Illness": {
      "Onset and Duration": string;
      "Associated Symptoms": string;
      "Aggravating and Alleviating Factors": string;
      "Severity of Symptoms": string;
    };
    "Summary": string;              // Comprehensive clinical narrative
    "Past Medical History": {
      "Chronic Illnesses": string;
      "Previous Hospitalizations": string;
      "Surgeries": string;
      "Allergies": string;
    };
    "Family History": string;
    "Social History": {
      "Social Support": string;
      "Occupation": string;
      "Lifestyle Factors": string;
      "Exercise and Diet": string;
    };
    "Medications": {
      "Current Medications": Array<{
        "Name": string;
        "Brand Name": string;
        "Generic Name": string;
        "Dosage": string;
        "Frequency": string;
        "Formulation": string;
        "Route": string;
        "Duration": string;
      }>;
    };
    "Review of Systems": {
      "General": string;
      "Cardiovascular": string;
      "Respiratory": string;
      "Gastrointestinal": string;
      "Genitourinary": string;
      "Musculoskeletal": string;
      "Neurological": string;
      "Mental Health Screening": string;
      "Psychiatric": string;
      "Endocrine": string;
      "Dermatological": string;
    };
  };
}

Example Payload

Section titled “Example Payload”
{
  "appointmentId": "2308",
  "transactionId": "t3zL38PrPDaFp2fLL4DvtY",
  "dateCreated": "2025-09-22T07:18:55.914786Z",
  "emergency_patient": false,
  "sourcePatientId": "urn:uuid:9b1d4c7e-2f3a-4e8b-a6d5-0c1f2e3d4b5a",
  "sourceappointmentId": "urn:uuid:3f6c1a52-8d7e-4b0f-9a1c-2e5d7b8c9f01",
  "intakeSummary": {
    "Patient Information": {
      "Date of Birth/Age": "18",
      "Gender": "male"
    },
    "Chief Complaint": "flu, fever, cold",
    "History of Present Illness": {
      "Onset and Duration": "symptoms started 3 days ago, fever started 2 days ago",
      "Associated Symptoms": "cold",
      "Aggravating and Alleviating Factors": "Unremarkable",
      "Severity of Symptoms": "fever at 102 Celsius"
    },
    "Summary": "The patient is an 18-year-old male with no known comorbidities or allergies.\n\nThe patient presents with a fever, flu, and cold, reporting a temperature of 102 degrees Celsius. Symptoms began three days ago, with the fever starting two days ago.\n\nThe patient has no known allergies, no comorbidities such as diabetes or high blood pressure, and has no history of surgeries.\n\nThe patient is currently taking Panadol Extra, 30 mg, twice a day for the fever and cold symptoms. He is not taking any other medications.\n\nThere is no available information on the patient's family history, social history, lifestyle, diet, habits, or addictions.\n\nReview of systems is unremarkable.",
    "Past Medical History": {
      "Chronic Illnesses": "Unremarkable",
      "Previous Hospitalizations": "Unremarkable",
      "Surgeries": "No surgeries",
      "Allergies": "No known allergies"
    },
    "Family History": "Not asked",
    "Social History": {
      "Social Support": "Not asked",
      "Occupation": "Not asked",
      "Lifestyle Factors": "Not asked",
      "Exercise and Diet": "Not asked"
    },
    "Medications": {
      "Current Medications": [
        {
          "Name": "Panadol Extra",
          "Brand Name": "Panadol Extra",
          "Generic Name": "",
          "Dosage": "30mg",
          "Frequency": "Twice a day",
          "Formulation": "tablet",
          "Route": "oral",
          "Duration": "since symptoms started"
        }
      ]
    },
    "Review of Systems": {
      "General": "fever, cold",
      "Cardiovascular": "Not asked",
      "Respiratory": "Not asked",
      "Gastrointestinal": "Not asked",
      "Genitourinary": "Not asked",
      "Musculoskeletal": "Not asked",
      "Neurological": "Not asked",
      "Mental Health Screening": "Score not applicable",
      "Psychiatric": "Not asked",
      "Endocrine": "Not asked",
      "Dermatological": "Not asked"
    }
  }
}

Correlation and Status Fields

Section titled “Correlation and Status Fields”
FieldTypeDescription
appointmentIdstringHAMI appointment identifier for the intake
transactionIdstringOptional. The transactionId returned by the Universal Ingestion API for the bundle that started this intake. Use it to link the summary back to your original submission. Omitted if the intake did not come from an ingestion call.
dateCreatedstringWhen the summary was generated. UTC by default. Groups can choose to receive it in the patient’s local time zone.
emergency_patientbooleantrue if HAMI detected possible emergency symptoms during the intake. Treat it as a triage signal and route it to a clinician straight away.
sourcePatientIdstringOptional. The fullUrl of the Patient entry in your ingested bundle
sourceappointmentIdstringOptional. The fullUrl of the Appointment entry in your ingested bundle. Note the lowercase a in appointment.
intakeSummaryobjectThe AI-generated summary. Your group can be configured to leave out some sections (e.g. Review of Systems).

Response Schema

Section titled “Response Schema”

Your endpoint should return appropriate HTTP status codes to indicate the result of processing.

Success Response (200 OK)

Section titled “Success Response (200 OK)”

Return 200 OK when the summary is successfully received and processed.

{
  "success": true,
  "message": "Summary received and processed successfully"
}

Error Responses

Section titled “Error Responses”
Status CodeDescriptionWhen to Return
200 OKSuccessSummary successfully received and processed
400 Bad RequestInvalid payloadPayload format is invalid or missing required fields
401 UnauthorizedAuthentication failedInvalid or missing X-API-Key header
422 Unprocessable EntityValidation failedPayload is valid JSON but fails business validation
500 Internal Server ErrorProcessing errorInternal error occurred while processing the summary

Implementation Examples

Section titled “Implementation Examples”
import express from 'express';


const app = express();
app.use(express.json());


// Middleware to validate API key
function validateApiKey(req, res, next) {
  const apiKey = req.headers['x-api-key'];
  const validApiKey = process.env.HAMI_API_KEY;


  if (!apiKey || apiKey !== validApiKey) {
    return res.status(401).json({
      success: false,
      message: 'Invalid or missing API key'
    });
  }


  next();
}


// Webhook endpoint
app.post('/api/ai-summary', validateApiKey, async (req, res) => {
  try {
    const { appointmentId, dateCreated, intakeSummary } = req.body;


    // Validate required fields
    if (!appointmentId || !intakeSummary) {
      return res.status(400).json({
        success: false,
        message: 'Missing required fields: appointmentId or intakeSummary'
      });
    }


    // Find the appointment in your system
    const appointment = await findAppointmentById(appointmentId);


    if (!appointment) {
      return res.status(422).json({
        success: false,
        message: `Appointment ${appointmentId} not found`
      });
    }


    // Store the intake summary
    await storeIntakeSummary({
      appointmentId,
      dateCreated,
      summary: intakeSummary,
      receivedAt: new Date()
    });


    // Update appointment record
    await updateAppointmentWithSummary(appointmentId, intakeSummary);


    // Log the successful reception
    console.log(`Intake summary received for appointment ${appointmentId}`);


    res.status(200).json({
      success: true,
      message: 'Summary received and processed successfully'
    });


  } catch (error) {
    console.error('Error processing intake summary:', error);
    res.status(500).json({
      success: false,
      message: 'Internal server error while processing summary'
    });
  }
});


// Helper functions (implement based on your data layer)
async function findAppointmentById(appointmentId) {
  // Query your database for the appointment
  // Return appointment object or null
}


async function storeIntakeSummary(summaryData) {
  // Store the summary in your database
}


async function updateAppointmentWithSummary(appointmentId, summary) {
  // Update the appointment record with summary information
}


const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Webhook server listening on port ${PORT}`);
});

Summary Field Guidelines

Section titled “Summary Field Guidelines”

Patient Information

Section titled “Patient Information”
  • Date of Birth/Age: May contain actual birth date or just age
  • Gender: male, female, or other values as provided by patient

Chief Complaint

Section titled “Chief Complaint”

Free-text description of the patient’s main concerns or reasons for visit.

History of Present Illness

Section titled “History of Present Illness”

Structured information about the current condition:

  • Onset and Duration: When symptoms started and how long they’ve persisted
  • Associated Symptoms: Related symptoms the patient is experiencing
  • Aggravating and Alleviating Factors: What makes symptoms better or worse
  • Severity of Symptoms: Description of symptom intensity

Summary

Section titled “Summary”

A comprehensive clinical narrative synthesizing all collected information. This is a physician-ready summary that can be directly incorporated into clinical documentation.

Past Medical History

Section titled “Past Medical History”
  • Chronic Illnesses: Ongoing medical conditions
  • Previous Hospitalizations: History of hospital admissions
  • Surgeries: Surgical history
  • Allergies: Known allergies to medications, foods, or substances

Medications

Section titled “Medications”

Array of current medications with detailed information:

  • Name: Medication name as reported by patient
  • Brand Name and Generic Name: May be empty if not specified
  • Dosage: Dose and units
  • Frequency: How often taken
  • Formulation: tablet, capsule, liquid, etc.
  • Route: oral, topical, intravenous, etc.
  • Duration: How long the patient has been taking the medication

Review of Systems

Section titled “Review of Systems”

Systematic review of body systems. Fields may contain:

  • Specific findings: Reported symptoms
  • “Not asked”: Information not collected during intake
  • “Unremarkable”: No significant findings in that system

Handling “Not Asked” and “Unremarkable” Values

Section titled “Handling “Not Asked” and “Unremarkable” Values”

The intake summary may contain fields with values:

  • “Not asked”: HAMI did not inquire about this information during the conversation
  • “Unremarkable”: The patient was asked, and reported no significant findings
  • Empty string (""): Information not provided or not applicable

Your system should handle these values appropriately based on your clinical workflow requirements.

Best Practices

Section titled “Best Practices”

Endpoint Design

Section titled “Endpoint Design”
  • Performance: Respond within 15 seconds (store first, process afterwards)
  • Asynchronous Processing: Process summaries asynchronously if your workflow is complex
  • Health Checks: Implement health check endpoints for monitoring
  • Logging: Log all incoming requests with appointment IDs for debugging
  • Monitoring: Set up alerts for repeated failures

Data Handling

Section titled “Data Handling”
  • Repeat deliveries: The same appointmentId can arrive more than once when a summary is regenerated. Keep the one with the latest dateCreated.
  • Version Management: Store multiple versions if patients update their intake multiple times
  • Merge Strategy: Decide whether to replace or merge when receiving updated summaries
  • Data Validation: Validate appointment IDs exist before storing summaries
  • Conflict Resolution: Define how to handle conflicts with existing patient data

Security

Section titled “Security”
  • API Key Storage: Store API keys in environment variables or secure key management systems
  • HTTPS Only: Never accept requests over HTTP
  • Rate Limiting: Implement rate limiting to prevent abuse
  • Authentication Logging: Log all authentication failures for security monitoring
  • HIPAA Compliance: Ensure all data handling is HIPAA compliant

Error Recovery

Section titled “Error Recovery”
  • Comprehensive Logging: Log all requests, successes, and failures with sufficient detail
  • Alerting: Set up alerts for repeated failures or unusual patterns
  • No automatic retry: A failed delivery isn’t re-sent automatically, so monitor for gaps (for example, appointments with no summary) and contact support to re-send
  • Fallback Procedures: Establish manual procedures when automated posting fails

Support

Section titled “Support”

For additional support or questions about the Intake Summary Webhook: