> ## 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 Status Change

## Overview

When a claim's status changes in CAIR (e.g. submitted, rejected, failed to submit), the system can send a webhook to your endpoint so you can keep your systems aligned with CAIR. This is useful for downstream systems (e.g. practice management or billing tools) that need to reflect the same status.

## When the webhook is sent

The `CLAIM_STATUS_CHANGE` webhook is sent when the claim status is updated to:

* **Submitted** – after a successful submission (professional or dental) to the clearinghouse, or when a user manually marks a claim as submitted
* **Rejected** – when a 277 CA (claim acknowledgment) indicates the claim was rejected by the payer (e.g. status codes 6, 12, 15, etc.)
* **Failed\_To\_Submit** – when submission to the clearinghouse fails (e.g. network error, validation error)
* **Forwarded** - when claim has been auto-forwarded to the secondary payer

The same event is used for primary, resubmitted, and secondary claims because they share the same status-update paths.

## Setup

1. Go to [Developer Settings](https://forecaster.cairhealth.com/developer-settings) → Webhooks
2. Create a new webhook
3. Set **Event Type** to `CLAIM_STATUS_CHANGE`
4. Configure URL, credentials, and description

## Event type

| Event Type            | Description                                             |
| --------------------- | ------------------------------------------------------- |
| `CLAIM_STATUS_CHANGE` | Notifications when a claim’s status changes (see above) |

## Payload format

Each request body is JSON with the following fields:

| Field                     | Type       | Description                                                                    |
| ------------------------- | ---------- | ------------------------------------------------------------------------------ |
| `claimFhirId`             | string     | FHIR ID of the claim (stable across CAIR)                                      |
| `claimLifecycleId`        | string     | CAIR claim lifecycle ID (used in URLs and APIs)                                |
| `claimControlNumber`      | string     | Unique identifier for the claim (submitted as the patient control number)      |
| `organizationId`          | string     | Organization that owns the claim                                               |
| `newStatus`               | string     | New claim status (e.g. `Submitted`, `Rejected`, `Failed_To_Submit`)            |
| `previousStatus`          | string?    | Previous status, when known (e.g. manual “mark as submitted”)                  |
| `timestamp`               | string     | ISO 8601 time when the status change was recorded                              |
| `submissionFailureErrors` | string\[]? | Present when `newStatus` is `Failed_To_Submit`; error messages from submission |
| `statusCode277`           | string?    | Present when `newStatus` is `Rejected`; 277 CA claim status code from payer    |

### Example (Submitted)

```json theme={null}
{
  "claimFhirId": "44f484fc-7946-44e2-bfad-bad583c479f5",
  "claimLifecycleId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "claimControlNumber": "12345",
  "organizationId": "org-uuid",
  "newStatus": "Submitted",
  "timestamp": "2025-03-11T14:30:00.000Z"
}
```

### Example (Rejected)

```json theme={null}
{
  "claimFhirId": "44f484fc-7946-44e2-bfad-bad583c479f5",
  "claimLifecycleId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "claimControlNumber": "12345",
  "organizationId": "org-uuid",
  "newStatus": "Rejected",
  "timestamp": "2025-03-11T14:35:00.000Z",
  "statusCode277": "12"
}
```

### Example (Failed\_To\_Submit)

```json theme={null}
{
  "claimFhirId": "44f484fc-7946-44e2-bfad-bad583c479f5",
  "claimLifecycleId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "claimControlNumber": "12345",
  "organizationId": "org-uuid",
  "newStatus": "Failed_To_Submit",
  "timestamp": "2025-03-11T14:32:00.000Z",
  "submissionFailureErrors": ["Failed to submit claim (HTTP 400)."]
}
```

## Authentication

Same as other CAIR webhooks: you can use **API\_SECRET** or **HMAC\_SHA256** in the webhook credentials. The secret is sent in the configured header with each request.