Webhook
Register and manage webhook endpoints to receive real-time event notifications from the Najeeb system. Webhooks allow your application to be notified when events occur, such as Prior Authorization processing completion and async bulk Policy operations, and claims batch status updates.
Base URL:
https://api.{client_namespace}.najeeb.ai/v4.0/health
Create Webhook
POST /webhook/create
Register a new webhook endpoint to receive event notifications. Once created, the webhook is immediately active and will begin receiving events of the specified type.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
webhook_url | string | Yes | The URL that will receive webhook event payloads via HTTP POST |
hook_type | enum | Yes | Event type to subscribe to. One of: CLAIM, PRE_AUTH, BOTH, POLICY, PRE_AUTH_RESULT (required to receive prior authorization decision results), CLAIM_RESULT (single-claim results of Claims as a Service), COMMUNICATION, REOPENED, REFERRED |
secret_token | string | No | Secret token for verifying webhook payloads on your end |
Request Example
- cURL
- JavaScript
- Python
curl -X POST \
"https://api.{client_namespace}.najeeb.ai/v4.0/health/webhook/create" \
-H "access-key: your-api-key-here" \
-H "Content-Type: application/json" \
-d '{
"webhook_url": "https://example.com/my-webhook-endpoint",
"hook_type": "BOTH",
"secret_token": "1234567890"
}'
const response = await fetch(
"https://api.{client_namespace}.najeeb.ai/v4.0/health/webhook/create",
{
method: "POST",
headers: {
"access-key": "your-api-key-here",
"Content-Type": "application/json",
},
body: JSON.stringify({
webhook_url: "https://example.com/my-webhook-endpoint",
hook_type: "BOTH",
secret_token: "1234567890",
}),
}
);
const data = await response.json();
console.log(data);
import requests
url = "https://api.{client_namespace}.najeeb.ai/v4.0/health/webhook/create"
payload = {
"webhook_url": "https://example.com/my-webhook-endpoint",
"hook_type": "BOTH",
"secret_token": "1234567890",
}
headers = {
"access-key": "your-api-key-here",
"Content-Type": "application/json",
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
Response
201 Created
{
"id": 1,
"webhook_url": "https://example.com/my-webhook-endpoint",
"hook_type": "BOTH",
"secret_token": "1234567890",
"is_active": true,
"created_at": "2021-01-01T00:00:00.000Z"
}
Error Responses
| Status | Description |
|---|---|
| 400 | Bad Request - Invalid or missing fields (e.g., invalid URL, missing hook_type) |
| 401 | Unauthorized - Invalid or missing access-key |
List Webhooks
GET /webhook/list
Returns all registered webhooks for your account.
Request Example
- cURL
- JavaScript
- Python
curl -X GET \
"https://api.{client_namespace}.najeeb.ai/v4.0/health/webhook/list" \
-H "access-key: your-api-key-here"
const response = await fetch(
"https://api.{client_namespace}.najeeb.ai/v4.0/health/webhook/list",
{
method: "GET",
headers: {
"access-key": "your-api-key-here",
},
}
);
const data = await response.json();
console.log(data);
import requests
url = "https://api.{client_namespace}.najeeb.ai/v4.0/health/webhook/list"
headers = {
"access-key": "your-api-key-here",
}
response = requests.get(url, headers=headers)
print(response.json())
Response
200 OK
{
"data": [
{
"id": 1,
"webhook_url": "https://example.com/my-webhook-endpoint",
"hook_type": "BOTH",
"secret_token": "1234567890",
"is_active": true,
"created_at": "2021-01-01T00:00:00.000Z"
}
]
}
Error Responses
| Status | Description |
|---|---|
| 401 | Unauthorized - Invalid or missing access-key |
Remove Webhook
DELETE /webhook/remove/:id
Remove a registered webhook. The webhook will stop receiving event notifications.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | ID of the webhook to remove |
Request Example
- cURL
- JavaScript
- Python
curl -X DELETE \
"https://api.{client_namespace}.najeeb.ai/v4.0/health/webhook/remove/1" \
-H "access-key: your-api-key-here"
const webhookId = 1;
const response = await fetch(
`https://api.{client_namespace}.najeeb.ai/v4.0/health/webhook/remove/${webhookId}`,
{
method: "DELETE",
headers: {
"access-key": "your-api-key-here",
},
}
);
const data = await response.json();
console.log(data);
import requests
webhook_id = 1
url = f"https://api.{{client_namespace}}.najeeb.ai/v4.0/health/webhook/remove/{webhook_id}"
headers = {
"access-key": "your-api-key-here",
}
response = requests.delete(url, headers=headers)
print(response.json())
Response
200 OK
Returns the removed webhook data with is_active set to false.
{
"id": 1,
"webhook_url": "https://example.com/my-webhook-endpoint",
"hook_type": "BOTH",
"secret_token": "1234567890",
"is_active": false,
"created_at": "2021-01-01T00:00:00.000Z"
}
Error Responses
| Status | Description |
|---|---|
| 401 | Unauthorized - Invalid or missing access-key |
| 404 | Not Found - Webhook with given ID not found |
Event Example Payloads
Webhook event payloads vary by hook_type. Select a tab below for an example.
- PRE_AUTH_RESULT
- REOPENED
- POLICY
- CLAIM
To receive prior authorization decision results, register a webhook with hook_type set to PRE_AUTH_RESULT. After the Najeeb Engine finishes processing a pre-authorization request, the final decision is delivered to your webhook endpoint as an HTTP POST.
For when it is sent, the full field reference and the automation fields, see Prior Authorization — Webhook Response.
{
"event_type": "PRE_AUTH_RESULT",
"data": {
"pre_auth_internal_id": 161081,
"transaction_id": "550e8400-e29b-41d4-a716-446655440001",
"authorization_number": "AU-12345",
"nphies_reopen_at": null,
"nphies_reopen_reason": null,
"submitter_erp_id": null,
"approval_remarks": "This is a test prior authorization",
"referral_remarks": null,
"internal_referral_notes": null,
"is_referred": false,
"is_request_automated": false,
"request_automation_note": null,
"internal_notes": null,
"request_alerts": [
"A prior authorization for the same diagnosis and service was previously submitted and rejected."
],
"issues": [
{
"level": "WARNING",
"code": "SIMILAR_REJECTED_REQUESTS",
"message": "A prior authorization for the same diagnosis and service was previously submitted and rejected."
}
],
"status": "PARTIALLY_ACCEPTED",
"reviewer_erp_id": null,
"member_id": "uat-a-002",
"source": null,
"is_emergency": false,
"is_new_born": false,
"is_maternity": false,
"related_authorization_number": null,
"claim_type": null,
"treatment_date": "2024-02-15T10:00:00.000Z",
"period_start_date": null,
"doctor_id": "1",
"doctor_name": "Dr. Ahmed",
"doctor_speciality": "Cardiology",
"nphies_bundle_id": null,
"provider_system_id": "Provider System ID",
"provider_comment": "Provider Comment",
"ERP_user_id": null,
"price_list_level": null,
"patient_id": "uat-a-002",
"medical_provider_cchi_no": "22697412",
"ph_erp_id": "UAT-policy-id-01",
"currency": "SAR",
"currency_rate": 1,
"is_reviewer_accepted_as_road_traffic_accident": false,
"is_traffic_accident": false,
"assign_to_erp_id": null,
"additional_remarks": "Patient requires cardiac evaluation",
"total_recovery_utilized": 0,
"total_exgratia_utilized": 0,
"benefit_code": null,
"is_referral": false,
"referral_provider_cchi_code": null,
"valid_days": null,
"referred_at": null,
"encounter": {
"encounter_id": null,
"encounter_status": "active",
"encounter_class": "outpatient",
"encounter_priority": null,
"encounter_start_date": null,
"encounter_end_date": null,
"encounter_arrival_code": null,
"encounter_department": "Cardiology",
"encounter_triage_category": null,
"encounter_triage_date": null,
"encounter_death_cause": null,
"encounter_admit_source": null,
"encounter_length_of_stay": null,
"encounter_admission": null,
"encounter_discharge": null
},
"items_decisions": [
{
"id": 501,
"item_erp_id": "ITEM-001",
"service_code": "FMCARS0008",
"duration": null,
"frequency": null,
"admission_date": null,
"discharge_date": null,
"approved_quantity": 1,
"approved_amount": 100,
"price": 100,
"request_amount": 100,
"provider_deductible_mount": 0,
"net_request_amount": 100,
"rejected_amount": 0,
"price_rejected_amount": 0,
"net_payable": 100,
"decision": "ACCEPTED",
"status": "ACCEPTED",
"warning_message": null,
"benefit_code": 10,
"sub_benefit_code": 1001,
"reason_code": [],
"najeeb_ai_alert": "",
"najeeb_ai_score": null,
"is_item_automated": true,
"item_automation_note": "This item was accepted automatically by the system.",
"pbm_drug_info": null,
"treatment_date": null
},
{
"id": 502,
"item_erp_id": "ITEM-002",
"service_code": "9-420-05",
"duration": null,
"frequency": "OD",
"admission_date": null,
"discharge_date": null,
"approved_quantity": 0,
"approved_amount": 0,
"price": 1871.95,
"request_amount": 1871.95,
"provider_deductible_mount": 0,
"net_request_amount": 1871.95,
"rejected_amount": 0,
"price_rejected_amount": 0,
"net_payable": 0,
"decision": "REJECTED",
"status": "REJECTED",
"warning_message": null,
"benefit_code": 10,
"sub_benefit_code": 1001,
"reason_code": [
{
"najeeb_ai_code": "AD-2-5",
"najeeb_ai_description": "Time limit for submission has expired",
"najeeb_ai_message": "The time difference between the treatment date and the request date is more than 24 hours.",
"nphies_code": "AD-2-5",
"nphies_description": "Time limit for submission has expired",
"special_case_amount": null,
"erp_code": null,
"is_approved": false,
"severity": null,
"source": "RULES"
}
],
"najeeb_ai_alert": "Diagnosis \"Z24\" is invalid / inactive as per the ICD AM 10th Ed. Electronic Code List Edits.",
"najeeb_ai_score": 0,
"is_item_automated": false,
"item_automation_note": null,
"pbm_drug_info": {
"id": 3210,
"sfda_code": "9-420-05",
"name": "Hepsera 10 mg tablet",
"scientific_name": "adefovir dipivoxil",
"manufacture_name": "Hepsera",
"pharmaceutical_form": "Tablet",
"strength": "10",
"unit": "mg",
"package_size": "30.000",
"price": 1871.95
},
"treatment_date": null
}
]
}
}
To receive reopen notifications, register a webhook with hook_type set to REOPENED. After a prior authorization is reopened, the updated request payload is delivered to your webhook endpoint as an HTTP POST.
For the full field reference, see Prior Authorization — Webhook Response. See also Reopen Prior Authorization.
{
"event_type": "REOPENED",
"data": {
}
}
To receive notifications when an async bulk operation completes, register a webhook with hook_type set to POLICY. After a bulk patient-to-policy operation finishes, the result summary is delivered to your webhook endpoint as an HTTP POST.
See also Async Add Bulk Patients to Policy.
{
"event_type": "POLICY",
"data": {
"event": "bulk-patient-to-policy-completed",
"jobId": "550e8400-e29b-41d4-a716-446655440000",
"policy_no": "POL-2024-001",
"ph_erp_id": "PH123456",
"summary": {
"total": 5,
"succeeded": 2,
"failed": 3
},
"errors": [
{
"member_id": "MEM-001",
"error_code": "E_EPA_017",
"message": "Category with code CAT-X not found"
},
{
"member_id": "MEM-002",
"error_code": "E_EIP_04",
"message": "Patient already has a policy, the patient uuid is: MEM-002"
},
{
"member_id": "MEM-003",
"error_code": "E_EIP_06",
"message": "We Don't have annual limit for this category CAT-A"
}
]
}
}
Payload Fields
| Field | Type | Description |
|---|---|---|
event_type | string | Always POLICY for policy-related events |
data.event | string | The specific event name: bulk-patient-to-policy-completed |
data.jobId | string | Unique identifier for the bulk operation job |
data.policy_no | string | The policy number the patients were added to |
data.ph_erp_id | string | The ERP ID of the policy holder |
data.summary.total | number | Total number of patients in the bulk request |
data.summary.succeeded | number | Number of patients successfully added |
data.summary.failed | number | Number of patients that failed to be added |
data.errors | array | Array of error objects for each failed patient |
data.errors[].member_id | string | The member ID that failed |
data.errors[].error_code | string | Error code identifying the failure reason |
data.errors[].message | string | Human-readable error description |
Common Error Codes
| Error Code | Description |
|---|---|
E_EPA_017 | Category not found for the given code |
E_EIP_04 | Patient already has an active policy |
E_EIP_06 | No annual limit configured for the given category |
To receive batch notifications, register a webhook with hook_type set to CLAIM. Najeeb sends an HTTP POST every time the status of a claims batch changes: when the batch is created, when validation fails, when processing starts, when processing finishes, and on every later status update.
See also Claims as a Service: CLAIM Webhook. Single claims send their result to CLAIM_RESULT; see CLAIM_RESULT Webhook.
Batch created (VALIDATING)
{
"event_type": "CLAIM",
"data": {
"event": "webHook.pushResultBack",
"batch_id": 801230,
"batch_erp_id": "BATCH-2026-0914-001",
"status": "VALIDATING"
}
}
Validation failed (FAILED)
{
"event_type": "CLAIM",
"data": {
"event": "webHook.pushResultBack",
"batch_id": 801230,
"batch_erp_id": "BATCH-2026-0914-001",
"status": "FAILED",
"payload": [
{
"claim_number": "CLM-1042",
"column": "Gender",
"error": "gender must be one of the following values: MALE, FEMALE"
}
]
}
}
Processing finished (PENDING_AUDIT)
{
"event_type": "CLAIM",
"data": {
"event": "webHook.pushResultBack",
"batch_id": 801230,
"batch_erp_id": "BATCH-2026-0914-001",
"status": "PENDING_AUDIT"
}
}
Payload Fields
| Field | Type | Description |
|---|---|---|
event_type | string | Always CLAIM for batch events |
data.event | string | Always webHook.pushResultBack |
data.batch_id | number | Najeeb's ID of the batch |
data.batch_erp_id | string | The batch_erp_id you sent when uploading the batch |
data.status | enum | The new batch status. See the table below |
data.payload | array | Only sent with FAILED. Validation errors, at most 100. Read all of them with Get Validation Errors. Empty when the file had no processable rows |
data.payload[].claim_number | string | The claim_id of the claim the error belongs to |
data.payload[].column | string | The column that failed validation |
data.payload[].error | string | Human-readable error description |
The FAILED event carries at most 100 validation errors. When a batch has more, read every error with Get Validation Errors (GET /batch/validation-errors/{batch_erp_id}).
Batch Statuses
| Status | When it is sent |
|---|---|
VALIDATING | The batch was created and initial validation started |
FAILED | Validation failed, or the file had no processable rows. payload lists the errors |
PROCESSING | Validation passed and the batch was sent to the AI engine |
REJECTED | The batch was not sent to the AI engine |
PENDING_AUDIT | AI processing finished and results are ready |
AUDITING | The batch was opened for audit |
AUDIT_COMPLETED | Audit finished |
SETTLED | The batch was settled |
PAID | The batch was marked as paid |
Related Resources
- Prior Authorization - Prior Authorization and claim events that trigger webhook notifications
- Prior Authorization - Field reference for the decision result payload
- Policy - Async bulk policy events that trigger webhook notifications
- Claims as a Service - Batch status events sent to
CLAIMwebhooks, and single-claim results sent toCLAIM_RESULTwebhooks - Overview - Back to API overview