​
FHIR ClaimResponse Webhooks

Cair Health provides a webhook system that allows you to receive real-time notifications when FHIR ClaimResponse resources are created or updated in the system. This enables you to integrate your systems with Cair Health and respond to claim adjudication events as they happen.

​
Overview

When a ClaimResponse resource is processed in the Cair Health platform, the system can automatically send this data to your specified endpoint. This allows you to:
  • Receive real-time notifications of claim adjudication results
  • Integrate claim data directly into your systems
  • Trigger automated workflows based on claim outcomes
  • Maintain synchronized data between Cair Health and your systems

​
Setup

To enable webhook delivery for ClaimResponse resources:
  1. Navigate to your Developer Settings
  2. Go to the Webhooks section
  3. Create a new webhook with the following information:
    • URL: The endpoint where you want to receive webhook payloads
    • Event Type: Select the event types you want to subscribe to (see below)
    • Description: A helpful description for your reference
    • Credentials: Set up authentication credentials for secure delivery

​
Event Types

You can subscribe to the following event types for ClaimResponse resources:
Event TypeDescription
CLAIMS_REMIT_ALLReceive all claim remittance advice (both approved and denied)
CLAIMS_REMIT_APPROVEDReceive only approved claim remittance advice
CLAIMS_REMIT_DENIEDReceive only denied claim remittance advice

​
Authentication

For security, webhooks can be authenticated using API keys. When setting up your webhook, you can configure:
  • Authentication Type: Currently supports API_SECRET
  • Header Name: The HTTP header that will contain your secret (e.g., X-API-KEY)
  • Secret: The secret value that will be sent with each webhook request

​
Payload Format

The webhook payload is a FHIR Collection Bundle containing both the ClaimResponse and Patient resources in JSON format. Here is the official FHIR R4B ClaimResponse documentation and here is the Patient documentation. Below is an example of what you might receive: 
{
  "resourceType": "Bundle",
  "type": "collection",
  "entry": [
    {
      "resource": {
        "resourceType": "ClaimResponse",
        "id": "01057264-665b-49e4-9cdc-014a88c18f20",
        "status": "active",
        "type": {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/claim-type",
              "code": "professional"
            }
          ]
        },
        "use": "claim",
        "patient": {
          "reference": "Patient/550e8400-e29b-41d4-a716-446655440000"
        },
        "created": "2024-11-01",
        "insurer": {
          "display": "Payer"
        },
        "request": {
          "reference": "Claim/44f484fc-7946-44e2-bfad-bad583c479f5",
          "type": "Claim"
        },
        "outcome": "complete",
        "disposition": "approved",
        "identifier": [
          {
            "system": "https://fhir.cairhealth.com/fhir/identifier/claim-response-id",
            "value": "37811511224852"
          }
        ],
        "item": [
          {
            "itemSequence": 1,
            "adjudication": [
              {
                "category": {
                  "coding": [
                    {
                      "system": "http://terminology.hl7.org/CodeSystem/adjudication",
                      "code": "submitted",
                      "display": "Submitted Amount"
                    }
                  ]
                },
                "amount": {
                  "value": 190.44,
                  "currency": "USD"
                }
              },
              {
                "category": {
                  "coding": [
                    {
                      "system": "http://terminology.hl7.org/CodeSystem/adjudication",
                      "code": "benefit",
                      "display": "Benefit"
                    }
                  ]
                },
                "amount": {
                  "value": 178.44,
                  "currency": "USD"
                }
              },
              {
                "category": {
                  "coding": [
                    {
                      "system": "https://x12.org/codes/claim-adjustment-group-codes",
                      "code": "CO",
                      "display": "Contractual Obligations"
                    }
                  ]
                },
                "reason": {
                  "coding": [
                    {
                      "system": "https://x12.org/codes/claim-adjustment-reason-codes",
                      "code": "45",
                      "display": "Charge exceeds fee schedule/maximum allowable or contracted/legislated fee arrangement."
                    }
                  ]
                },
                "amount": {
                  "value": 12,
                  "currency": "USD"
                }
              }
            ]
          }
        ],
        "payment": {
          "type": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/ex-paymenttype",
                "code": "complete"
              }
            ]
          },
          "date": "2024-11-01",
          "amount": {
            "value": 178.44,
            "currency": "USD"
          }
        }
      }
    },
    {
      "resource": {
        "resourceType": "Patient",
        "id": "patient-id-123",
        "identifier": [
          {
            "use": "official",
            "type": {
              "coding": [
                {
                  "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                  "code": "MR",
                  "display": "Medical Record Number"
                }
              ]
            },
            "system": "https://fhir.cairhealth.com/Organization/test/NamingSystem/test-org-mr",
            "value": "550e8400-e29b-41d4-a716-446655440000"
          }
        ],
        "name": [
          {
            "use": "official",
            "family": "Smith",
            "given": ["John", "Michael"]
          }
        ],
        "gender": "male",
        "birthDate": "1990-01-01"
      }
    }
  ]
}
The bundle contains two resources:
  1. ClaimResponse: The claim adjudication result with payment information, adjustments, and outcome details
  2. Patient: The patient information associated with the claim, including identifiers and demographic data