Webhook for Claims
Webhooks enable you to receive data to a specific URL whenever certain actions are performed on your integration. Each action is referred to as an event.
A webhook URL is an endpoint on your server where you can receive notifications about such events.
To Setup your webhook URL
- Login to the settings page of your organization's account on the web platform
- Go to developer access, there you would see where to specify your webhook URL.
Webhook Request and Response
Curacel sends claim webhook notifications as HTTP POST requests with a JSON body.
Your webhook endpoint should return any 2xx HTTP status code after receiving the payload successfully. If your endpoint returns a non-2xx response or does not respond before the request timeout, Curacel will retry the webhook delivery.
If webhook authorization is enabled for your organization, Curacel includes an Authorization header in the request:
Authorization: Bearer {access_token}
Events
Possible types of events to expect are below:
Note
For claim webhooks, the top-level name and event fields contain the same event name. Existing integrations should use event to determine the webhook type.
Claim Submitted
This event is triggered when a claim is submitted successfully.
The payload structure to expect is below:
JSON
{
"name": "claim.submitted",
"event": "claim.submitted",
"data": {
"id": 12345,
"pile_id": 678,
"ref": "CLAIM-REF-001",
"encounter_date": "2026-09-03T00:00:00.000000Z",
"amount_billed": 25000,
"approved_amount": 0,
"is_submitted": true,
"created_at": "2026-09-03T08:00:00.000000Z",
"updated_at": "2026-09-03T08:00:00.000000Z",
"submitted_at": "2026-09-03T08:00:00.000000Z",
"vetted_at": null,
"status": "Submitted",
"approval_status": null,
"co_payment_fee": null,
"provider": {
"id": 10,
"name": "Care Provider Hospital",
"code": "PROV-001"
},
"insurer": {
"id": 4,
"name": "Example HMO",
"code": "EXHMO"
},
"code": "EXHMO",
"enrollee": {
"id": 2001,
"insurance_no": "INS123456",
"first_name": "John",
"last_name": "Doe",
"birthdate": "1990-01-01",
"policy_start_date": "2026-01-01",
"sex": "male",
"is_floating": false,
"status": "active",
"hmo_plan": {
"id": 33,
"name": "Gold Plan"
},
"type": "principal",
"nin": null,
"tin": null,
"bvn": null,
"address": "12 Sample Street",
"phone": "08000000000",
"policy_end_date": "2026-12-31"
},
"diagnoses": [
{
"name": "Malaria",
"english_name": "Malaria",
"icd_code": "B54"
}
],
"items": [
{
"ref": "ITEM-001",
"description": "Consultation",
"unit_price_billed": 5000,
"unit_price_approved": null,
"qty_billed": 1,
"qty_approved": null,
"sub_total_billed": 5000,
"sub_total_approved": null,
"comments": null,
"status": null,
"tariff_match_status": null,
"tariff_match_source": null,
"tariff_match_confidence": null,
"tariff_match_description": null,
"tariff_match_normalized_description": null,
"tariff_match_candidates": null,
"tariff_pricing_status": null,
"tariff_pricing_source": null,
"benefit": null
}
],
"attachments": [
{
"id": 501,
"title": "Invoice",
"file_type": "pdf",
"filename": "invoice.pdf",
"file_url": "https://example.com/invoice.pdf"
}
],
"specialist_info": null,
"symptom_diagnosis_context": null
}
}
Claim Pile Vetting Done
This event is triggered after all claims in a pile have been vetted, gone through the entire process (including multiple audits if configured) and the pile has a status of 'Vetting Done'. It will be triggered for every single claim within the pile.
Note
The notification for each claim within a pile will be sent one after the other and not all at once, considering there are typically many claims in a pile so as not to overload your servers.
The payload structure to expect is below:
JSON
{
"event":"claim.pile.vetting_done",
"data":{
"id": {integer},
"pile_id": {integer},
"ref": {string},
"provider": {
"id": {integer},
"name": {string},
"code": {string}
},
"encounter_date": "2021-09-05T00:00:00.000000Z",
"enrollee_id": {integer},
"billed_amount": {float},
"approved_amount": {float},
"approval_status": {null, 0 or 1},
"vetted_at": "2022-02-16T16:17:32.000000Z",
"diagnoses": [
{
"name": {string},
"icd_code": {string}
}
],
"items": [
{
"ref": {string},
"description": {string},
"unit_price_billed": {integer},
"unit_price_approved": {integer},
"qty_billed": {integer},
"qty_approved": {integer},
"sub_total_billed": {integer},
"sub_total_approved": {integer},
"comments": {array}, //
"approval_status": {null, 0 or 1},
"benefit": {
"id": {integer},
"label": {string},
"source_type": {string},
"care_group": {
"id": {integer},
"name": {string}
}
}
}
]
}
}
Claim Vetted
This event is triggered when an individual claim has been vetted successfully regardless of whether the pile has been completely vetted or not.
The payload structure to expect is below:
JSON
{
"name": "claim.vetted",
"event": "claim.vetted",
"data": {
"id": 12345,
"pile_id": 678,
"ref": "CLAIM-REF-001",
"encounter_date": "2026-09-03T00:00:00.000000Z",
"amount_billed": 25000,
"approved_amount": 20000,
"is_submitted": true,
"created_at": "2026-09-03T08:00:00.000000Z",
"updated_at": "2026-09-03T09:00:00.000000Z",
"submitted_at": "2026-09-03T08:00:00.000000Z",
"vetted_at": "2026-09-03T09:00:00.000000Z",
"status": "Vetted",
"approval_status": 1,
"co_payment_fee": null,
"provider": {
"id": 10,
"name": "Care Provider Hospital",
"code": "PROV-001"
},
"insurer": {
"id": 4,
"name": "Example HMO",
"code": "EXHMO"
},
"code": "EXHMO",
"enrollee": {
"id": 2001,
"insurance_no": "INS123456",
"first_name": "John",
"last_name": "Doe",
"birthdate": "1990-01-01",
"policy_start_date": "2026-01-01",
"sex": "male",
"is_floating": false,
"status": "active",
"hmo_plan": {
"id": 33,
"name": "Gold Plan"
},
"type": "principal",
"nin": null,
"tin": null,
"bvn": null,
"address": "12 Sample Street",
"phone": "08000000000",
"policy_end_date": "2026-12-31"
},
"diagnoses": [
{
"name": "Malaria",
"english_name": "Malaria",
"icd_code": "B54"
}
],
"items": [
{
"ref": "ITEM-001",
"description": "Consultation",
"unit_price_billed": 5000,
"unit_price_approved": 5000,
"qty_billed": 1,
"qty_approved": 1,
"sub_total_billed": 5000,
"sub_total_approved": 5000,
"comments": null,
"status": 1,
"tariff_match_status": null,
"tariff_match_source": null,
"tariff_match_confidence": null,
"tariff_match_description": null,
"tariff_match_normalized_description": null,
"tariff_match_candidates": null,
"tariff_pricing_status": null,
"tariff_pricing_source": null,
"benefit": {
"id": 44,
"label": "Outpatient Consultation",
"source_type": "care",
"care_group": {
"id": 12,
"name": "Consultation"
}
}
}
],
"attachments": [
{
"id": 501,
"title": "Invoice",
"file_type": "pdf",
"filename": "invoice.pdf",
"file_url": "https://example.com/invoice.pdf"
}
],
"specialist_info": null,
"symptom_diagnosis_context": null
}
}
Payload Data Description
| Attribute | Description |
|---|---|
| name | Event name. For claim webhooks, this is the same value as event. |
| event | Event name, for example claim.submitted or claim.vetted. |
| data | Claim payload for the event. |
| id | Id of the auto-vetted claim |
| pile_id | Id of the pile the claim belongs to |
| ref | Unique identifier for the claim on the source's system. |
| provider | Provider to which claim is attached |
| provider.id | The id of the provider |
| provider.name | The name of the provider |
| provider.code | The provider code |
| insurer | Insurer/HMO attached to the claim. |
| insurer.id | The id of the insurer/HMO. |
| insurer.name | The name of the insurer/HMO. |
| insurer.code | The insurer/HMO code. |
| code | Insurer/HMO code. |
| encounter_date | The encounter date |
| enrollee.id | Id of the enrollee |
| amount_billed | Total amount requested on the claim. |
| approved_amount | decimal-based value of the approved amount after auto-vetting |
| is_submitted | Indicates whether the claim has been submitted. |
| created_at | Claim creation timestamp. |
| updated_at | Claim last update timestamp. |
| submitted_at | Claim submission timestamp. |
| approval_status | status of the claim (0 = rejected, null = pending, 1 = approved). |
| vetted_at | A timestamp indicating when the claim was vetted |
| diagnoses[n] | Collection of claim diagnoses. |
| diagnoses[n].name | Unique name of the diagnosis |
| diagnoses[n].english_name | English diagnosis name. |
| diagnoses[n].icd_code | Unique icd code of diagnosis |
| items[n].ref | Unique identifier for the claim item as it is on the source system. E.g it’s id |
| items[n].description | Description of the service rendered to the enrollee |
| items[n].unit_price_billed | Requested unit price of the item |
| items[n].unit_price_approved | The approved unit price of the item after auto-vetting. |
| items[n].qty_billed | Quantity of the claim item |
| items[n].qty_approved | Approved quantity of claim item after auto-vetting |
| items[n].sub_total_billed | The total amount of claim item (unit_price_billed * qty) |
| items[n].sub_total_approved | The total amount of claim item (unit_price_approved * qty_approved) |
| items[n].comments | A collection of the claim item comments after auto-vetting |
| items[n].status | Approval status of the claim item. (null = pending, 0 = rejected, 1 = approved) |
| attachments[n] | Collection of claim attachments. |
| specialist_info | Specialist information submitted with the claim, if available. |
| symptom_diagnosis_context | Symptom-to-diagnosis context, if available. |
| items[n].benefit | Resolved benefit summary for the claim item based on the enrollee's active plan |
| items[n].benefit.id | The matched plan benefit ID |
| items[n].benefit.label | Human-readable benefit label |
| items[n].benefit.source_type | Match source such as care, care_group, or care_type |
| items[n].benefit.care_group | Present when the benefit match came from a care-group rule |