Skip to main content

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​

FieldTypeRequiredDescription
webhook_urlstringYesThe URL that will receive webhook event payloads via HTTP POST
hook_typeenumYesEvent 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_tokenstringNoSecret token for verifying webhook payloads on your end

Request Example​

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"
}'

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​

StatusDescription
400Bad Request - Invalid or missing fields (e.g., invalid URL, missing hook_type)
401Unauthorized - Invalid or missing access-key

List Webhooks​

GET /webhook/list

Returns all registered webhooks for your account.

Request Example​

curl -X GET \
"https://api.{client_namespace}.najeeb.ai/v4.0/health/webhook/list" \
-H "access-key: your-api-key-here"

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​

StatusDescription
401Unauthorized - Invalid or missing access-key

Remove Webhook​

DELETE /webhook/remove/:id

Remove a registered webhook. The webhook will stop receiving event notifications.

Path Parameters​

ParameterTypeRequiredDescription
idintegerYesID of the webhook to remove

Request Example​

curl -X DELETE \
"https://api.{client_namespace}.najeeb.ai/v4.0/health/webhook/remove/1" \
-H "access-key: your-api-key-here"

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​

StatusDescription
401Unauthorized - Invalid or missing access-key
404Not Found - Webhook with given ID not found

Event Example Payloads​

Webhook event payloads vary by hook_type. Select a tab below for an example.

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
}
]
}
}

  • 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 CLAIM webhooks, and single-claim results sent to CLAIM_RESULT webhooks
  • Overview - Back to API overview