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

Go to Developer Settings → Webhooks
Create a new webhook
Set Event Type to CLAIM_STATUS_CHANGE
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)

{
  "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)

{
  "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)

{
  "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.

Overview

API Authentication

Eligibility

Enrollments/Providers

Claims

Claim AI Actions

Patient Chart Analysis

Webhooks

AI Phone Calls

Overview

When the webhook is sent

Setup

Event type

Payload format

Example (Submitted)

Example (Rejected)

Example (Failed_To_Submit)

Authentication

​Overview

​When the webhook is sent

​Setup

​Event type

​Payload format

​Example (Submitted)

​Example (Rejected)

​Example (Failed_To_Submit)

​Authentication

Overview

When the webhook is sent

Setup

Event type

Payload format

Example (Submitted)

Example (Rejected)

Example (Failed_To_Submit)

Authentication