Skip to main content

​
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)
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 → Webhooks
  2. Create a new webhook
  3. Set Event Type to CLAIM_STATUS_CHANGE
  4. Configure URL, credentials, and description

​
Event type

Event TypeDescription
CLAIM_STATUS_CHANGENotifications when a claim’s status changes (see above)

​
Payload format

Each request body is JSON with the following fields:
FieldTypeDescription
claimFhirIdstringFHIR ID of the claim (stable across CAIR)
claimLifecycleIdstringCAIR claim lifecycle ID (used in URLs and APIs)
organizationIdstringOrganization that owns the claim
newStatusstringNew claim status (e.g. Submitted, Rejected, Failed_To_Submit)
previousStatusstring?Previous status, when known (e.g. manual “mark as submitted”)
timestampstringISO 8601 time when the status change was recorded
submissionFailureErrorsstring[]?Present when newStatus is Failed_To_Submit; error messages from submission
statusCode277string?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",
  "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",
  "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",
  "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.