> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cairhealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks: Claim Response

## 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](https://forecaster.cairhealth.com/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 Type              | Description                                                    |
| ----------------------- | -------------------------------------------------------------- |
| `CLAIMS_REMIT_ALL`      | Receive all claim remittance advice (both approved and denied) |
| `CLAIMS_REMIT_APPROVED` | Receive only approved claim remittance advice                  |
| `CLAIMS_REMIT_DENIED`   | Receive 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`, `HMAC-256`
* **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](http://hl7.org/fhir/R4B/claimresponse.html) is the official FHIR R4B ClaimResponse documentation and [here](http://hl7.org/fhir/R4B/patient.html) is the Patient documentation. Below is an example of what you might receive:

```json theme={null}
{
  "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