Webhooks

{
  "id": "evt_7x8y9z0a1b2c3d4e",
  "event": "call.completed",
  "api_version": "2024-12-01",
  "created_at": "2024-12-18T10:35:00.000Z",
  "data": {
    "object": "voice_call",
    // Event-specific data
  },
  "livemode": true
}

{
  "id": "evt_8f0f9c8f1f2a4b0bb5f3eae7c9d12b34",
  "event": "case.created",
  "api_version": "2025-12-26",
  "created_at": "2025-12-26T07:40:00.000Z",
  "data": {
    "object": "case",
    "id": "f7c2a5c6-3c2a-4c43-8e92-1a2b3c4d5e6f",
    "status": "open",
    "client_slug": "healthconnect",
    "widget_client_id": "0c7b3c4d-1a2b-4c43-8e92-3c2a5c6f7d8e"
  },
  "livemode": false
}

{
  "id": "evt_a1b2c3d4e5f6g7h8",
  "event": "call.started",
  "api_version": "2024-12-01",
  "created_at": "2024-12-18T10:30:00.000Z",
  "data": {
    "object": "voice_call",
    "id": 1847,
    "call_id": "conv_8701kb8rek5dfb7sc9qm",
    "phone_number": "+14155551234",
    "direction": "inbound",
    "call_type": "patient_inbound",
    "agent_type": "benefits",
    "status": "in_progress",
    "started_at": "2024-12-18T10:30:00.000Z"
  },
  "livemode": true
}

{
  "id": "evt_b2c3d4e5f6g7h8i9",
  "event": "call.completed",
  "api_version": "2024-12-01",
  "created_at": "2024-12-18T10:35:00.000Z",
  "data": {
    "object": "voice_call",
    "id": 1847,
    "call_id": "conv_8701kb8rek5dfb7sc9qm",
    "phone_number": "+14155551234",
    "direction": "inbound",
    "status": "completed",
    "patient_id": 456,
    "duration_seconds": 312,
    "call_outcome": "pa_required",
    "patient_satisfaction_score": 4,
    "verified": true,
    "verification_method": "name_dob_memberid",
    "topics_discussed": [
      "benefits_verification",
      "pa_requirements",
      "cost_sharing"
    ],
    "medications_discussed": ["Rixomab"],
    "jcodes_discussed": {
      "Rixomab": "J0000"
    },
    "analysis": {
      "summary": "Patient called to verify coverage for Rixomab. Prior authorization is required. Deductible has been met, patient has 20% coinsurance.",
      "key_findings": [
        "Prior authorization required for Rixomab",
        "Annual deductible of $1,500 has been met",
        "20% coinsurance applies after deductible",
        "PA can be submitted via fax or portal"
      ],
      "next_steps_for_patient": "Provider will submit PA request. Patient will be notified within 5-7 business days.",
      "internal_notes": "Patient was well-informed and satisfied with the information provided."
    },
    "follow_up_actions": [
      {
        "action": "Submit prior authorization",
        "assigned_to": "provider",
        "priority": "high",
        "status": "pending",
        "due_date": "2024-12-21"
      }
    ],
    "compliance_score": 94.5,
    "callback_requested": false,
    "email_summary_requested": true,
    "callback_email": "patient@email.com",
    "audio_url": "/api/v1/calls/1847/audio",
    "started_at": "2024-12-18T10:30:00.000Z",
    "completed_at": "2024-12-18T10:35:12.000Z"
  },
  "livemode": true
}

{
  "id": "evt_c3d4e5f6g7h8i9j0",
  "event": "adverse_event.reported",
  "api_version": "2024-12-01",
  "created_at": "2024-12-18T10:33:00.000Z",
  "data": {
    "object": "adverse_event",
    "id": 234,
    "case_number": "AE-456-1734517980",
    "voice_call_id": 1847,
    "patient_id": 456,
    "patient": {
      "id": 456,
      "first_name": "John",
      "last_name": "Doe",
      "mrn": "MRN1456"
    },
    "severity": "moderate",
    "requires_immediate_action": false,
    "description": "Patient reported persistent headache and mild fatigue starting 3 days after infusion",
    "medication_name": "Rixomab",
    "symptoms": [
      "headache",
      "fatigue",
      "mild nausea"
    ],
    "occurrence_date": "2024-12-15",
    "reported_date": "2024-12-18T10:33:00.000Z",
    "status": "pending_review",
    "medical_team_notified": false
  },
  "livemode": true
}

{
  "id": "evt_d4e5f6g7h8i9j0k1",
  "event": "pa.required",
  "api_version": "2024-12-01",
  "created_at": "2024-12-18T10:34:00.000Z",
  "data": {
    "object": "pa_requirement",
    "voice_call_id": 1847,
    "patient_id": 456,
    "medication_name": "Rixomab",
    "j_code": "J0000",
    "payer": {
      "id": "aetna",
      "name": "Aetna"
    },
    "plan": {
      "id": "aetna_ppo_2024",
      "name": "Aetna PPO Select"
    },
    "pa_on_file": false,
    "submission_methods": [
      {
        "method": "fax",
        "fax_number": "1-800-555-0199",
        "preferred": true
      },
      {
        "method": "portal",
        "portal_url": "https://portal.aetna.com/pa"
      }
    ],
    "turnaround_days": 5,
    "required_documents": [
      "Clinical notes",
      "Lab results",
      "Treatment history"
    ],
    "step_therapy_required": false,
    "identified_at": "2024-12-18T10:34:00.000Z"
  },
  "livemode": true
}

{
  "id": "evt_e5f6g7h8i9j0k1l2",
  "event": "callback.requested",
  "api_version": "2024-12-01",
  "created_at": "2024-12-18T10:34:30.000Z",
  "data": {
    "object": "callback_request",
    "voice_call_id": 1847,
    "patient_id": 456,
    "patient": {
      "id": 456,
      "first_name": "John",
      "last_name": "Doe",
      "phone": "+14155551234"
    },
    "callback_type": "phone",
    "callback_phone": "+14155551234",
    "reason": "Patient has questions about PA appeal process",
    "priority": "high",
    "preferred_time": "afternoon",
    "call_summary": "Patient verified coverage for Rixomab. PA is required. Patient wants to discuss appeal options if PA is denied.",
    "requested_at": "2024-12-18T10:34:30.000Z"
  },
  "livemode": true
}

{
  "id": "evt_g7h8i9j0k1l2m3n4",
  "event": "benefits.verified",
  "api_version": "2024-12-01",
  "created_at": "2024-12-18T10:36:00.000Z",
  "data": {
    "object": "benefit_verification",
    "id": 892,
    "patient_id": 456,
    "payer": {
      "id": "aetna",
      "name": "Aetna"
    },
    "plan": {
      "id": "aetna_ppo_2024",
      "name": "Aetna PPO Select"
    },
    "verification_sources": ["edi"],
    "voice_call_id": null,
    "status": "completed",
    "coverage_status": "active",
    "in_network": true,
    "deductible_individual": 1500,
    "deductible_met_ytd": 1500,
    "out_of_pocket_max": 6000,
    "out_of_pocket_met_ytd": 2340,
    "copay_specialist": 40,
    "coinsurance_percent": 20,
    "pa_required": null,
    "field_sources": {
      "coverage_status": "edi",
      "deductible_individual": "edi",
      "deductible_met_ytd": "edi",
      "copay_specialist": "edi",
      "coinsurance_percent": "edi"
    },
    "verified_at": "2024-12-18T10:36:02.000Z",
    "duration_seconds": 2
  },
  "livemode": true
}

curl https://api.isomera.ai/v1/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/isomera",
    "events": [
      "call.completed",
      "adverse_event.reported",
      "pa.required"
    ],
    "description": "Production EHR integration"
  }'

import hmac
import hashlib
import time

def verify_webhook(
    payload: bytes,
    signature: str,
    timestamp: str,
    secret: str,
    tolerance: int = 300  # 5 minutes
) -> bool:
    """Verify Isomera webhook signature."""

    # Check timestamp to prevent replay attacks
    current_time = int(time.time())
    request_time = int(timestamp)
    if abs(current_time - request_time) > tolerance:
        return False

    # Compute expected signature
    signed_payload = f"{timestamp}.".encode() + payload
    expected = hmac.new(
        secret.encode(),
        signed_payload,
        hashlib.sha256
    ).hexdigest()

    # Compare signatures
    return hmac.compare_digest(
        f"sha256={expected}",
        signature
    )

# Flask example
@app.route("/webhooks/isomera", methods=["POST"])
def handle_webhook():
    payload = request.get_data()
    signature = request.headers.get("X-Isomera-Signature")
    timestamp = request.headers.get("X-Isomera-Timestamp")
    delivery_id = request.headers.get("X-Isomera-Delivery-Id")

    if not verify_webhook(payload, signature, timestamp, WEBHOOK_SECRET):
        return "Invalid signature", 401

    # Check for duplicate delivery
    if is_duplicate(delivery_id):
        return "Already processed", 200

    event = json.loads(payload)

    # Route to handler based on event type
    match event["event"]:
        case "call.completed":
            handle_call_completed(event["data"])
        case "adverse_event.reported":
            handle_adverse_event(event["data"])
        case "pa.required":
            handle_pa_required(event["data"])

    return "OK", 200

1. RESPOND QUICKLY
   Return 2xx status within 30 seconds. Process
   events asynchronously in a background queue.

2. HANDLE DUPLICATES
   Use X-Isomera-Delivery-Id for idempotency.
   Store processed IDs to detect duplicates.

3. VERIFY SIGNATURES
   Always validate HMAC signature before processing.
   Never trust unverified payloads.

4. CHECK TIMESTAMPS
   Reject requests with timestamps > 5 minutes old
   to prevent replay attacks.

5. MONITOR FAILURES
   Set up alerts for repeated delivery failures.
   Review webhook logs regularly.

6. USE HTTPS
   Webhook URLs must use HTTPS with TLS 1.2+.
   Self-signed certificates are not supported.

curl -X POST https://api.isomera.ai/v1/webhooks/wh_abc123/test \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"event_type": "call.completed"}'