Webhooks

Partners who want to integrate with Altibbi can use webhooks to receive notifications about events that occur in the Altibbi system.

Delivery

Every webhook is an HTTP POST with a JSON body (content-type: application/json) and a 10 second timeout.
Each request carries your partner authentication header (the header name and value configured for your account).
Webhooks are sent on a best-effort basis and are not retried, so your endpoint should respond with a 2xx quickly and process the event asynchronously.
Your endpoint should be idempotent: use consultation_id, type and datetime to detect duplicates.
Status updates and consultation notifications are delivered to your status callback URL; recommendation webhooks are delivered to your recommendation callback URL. Both are configured with your account.

Common payload fields

Every webhook includes these fields:

Field	Type	Description
`type`	string	The webhook type, see the sections below
`consultation_id`	integer	The consultation the event belongs to
`user_id`	integer	The user who owns the consultation
`insurance_id`	string	The user's insurance id
`policy_number`	string	The user's policy number
`datetime`	string	When the event was sent (ISO 8601, UTC)

Webhook types

`type`	Delivered to	Description
`status_update`	status callback URL	The consultation status changed or its outcome was determined
`accept_consultation`	status callback URL	A doctor accepted the consultation
`doctor_no_answer`	status callback URL	The doctor tried to reach the patient and got no answer
`doctor_waiting_the_patient`	status callback URL	The doctor is waiting for the patient
`voip_notification`	status callback URL	VoIP call credentials are ready
`convert_voip_to_gsm_notification`	status callback URL	The VoIP call was converted to a GSM (phone) call
`video_notification`	status callback URL	Video call credentials are ready
`chat_notification`	status callback URL	Chat credentials are ready
`chat_history_notification`	status callback URL	The chat history of a chat consultation
`recommendation_data`	recommendation callback URL	The doctor's medical recommendation

1- Status update webhooks

Sent when the status of a consultation changes, and when the outcome of a consultation is determined.

Sample payload:

{
  "type": "status_update",
  "consultation_id": 72,
  "user_id": 1,
  "insurance_id": "1234",
  "policy_number": "1981",
  "old_status": "new",
  "new_status": "checking_medical_profile",
  "datetime": "2024-01-30T09:38:50.848860Z"
}

Consultation statuses

new_status can be one of the following lifecycle statuses:

Status	Description
`scheduled`	The consultation was booked for a later time and is waiting for its slot
`new`	The consultation is open and waiting for a doctor
`checking_medical_profile`	A doctor accepted the consultation and is reviewing the patient's medical profile and attachments
`in_progress`	The consultation session (chat, VoIP, video or GSM call) started
`closed`	The consultation ended. A closed consultation never changes status again

A typical flow is new → checking_medical_profile → in_progress → closed. A scheduled consultation becomes new when it is opened for doctors.

Consultation outcomes

After a consultation is closed, the status update webhook may also be sent with one of the following outcome values in new_status. These do not change the consultation status, so old_status is the current status of the consultation (normally closed):

Value	Description
`success`	The consultation was completed and rated successfully by the doctor
`failed`	The consultation was not completed, due to a technical issue or because the doctor did not get all the information from the patient

Sample payload:

{
  "type": "status_update",
  "consultation_id": 72,
  "user_id": 1,
  "insurance_id": "1234",
  "policy_number": "1981",
  "old_status": "closed",
  "new_status": "failed",
  "datetime": "2023-06-15T10:12:03.120331Z"
}

Notes

Duplicate or no-op transitions are not sent (for example new → new, or closed → closed).
Once a consultation is closed, later lifecycle status changes are ignored and no webhook is sent for them.
A consultation cancelled by the patient through the API is closed immediately and does not trigger a closed status webhook.
When a failed consultation is re-created, the new consultation is linked to the old one. No webhook is sent for the re-creation itself.

2- Consultation notification webhooks

These webhooks notify the partner about events that happen during the consultation. The event specific information is in the data field.

Common payload shape:

{
  "type": "accept_consultation",
  "consultation_id": 72,
  "user_id": 1,
  "insurance_id": "1234",
  "policy_number": "1981",
  "data": {},
  "datetime": "2023-06-15T09:40:12.331205Z"
}

`accept_consultation`

A doctor accepted the consultation.

"data": {
  "drName": "Dr. Sample Name",
  "drRating": 4.8
}

`doctor_no_answer`

The doctor tried to reach the patient and did not get an answer. Use it to prompt the patient to be available. data is informational and may be empty.

`doctor_waiting_the_patient`

The doctor is ready and waiting for the patient. Use it to prompt the patient to open the consultation. data is informational and may be empty.

`voip_notification`

The VoIP call is ready. Use these credentials to join the call.

"data": {
  "api_key": "47123456",
  "call_id": "2_MX40NzEyMzQ1Nn5-...",
  "token": "T1==cGFydG5lcl9pZD00NzEyMzQ1NiZzaWc9..."
}

`convert_voip_to_gsm_notification`

The VoIP call was converted to a GSM call. From this point the consultation medium is gsm.

`video_notification`

The video call is ready. Use these credentials to join the call.

"data": {
  "api_key": "47123456",
  "call_id": "2_MX40NzEyMzQ1Nn5-...",
  "token": "T1==cGFydG5lcl9pZD00NzEyMzQ1NiZzaWc9..."
}

`chat_notification`

The chat is ready. Use these credentials to join the chat group.

"data": {
  "appId": "1234567890abcdef",
  "groupId": "consultation_72",
  "chatUserId": "user_1",
  "chatUserToken": "a1b2c3d4e5f6..."
}

`chat_history_notification`

Sent once for a chat consultation with the chat history of the session in data.

caution

The voip_notification, video_notification and chat_notification payloads contain session credentials. Treat them as secrets: do not log them and do not expose them to anyone other than the patient who owns the consultation.

3- Recommendation webhooks

Sent to the recommendation callback URL once the doctor has prepared the medical recommendation, in json format. The recommendation is sent once per consultation. Sample payload:

{
  "type": "recommendation_data",
  "consultation_id": 72,
  "user_id": 1,
  "insurance_id": "1",
  "policy_number": "1",
  "data": {
    "icd10": {
      "symptom": [
        {
          "name": "Freckles",
          "code": "L81.2"
        }
      ],
      "diagnosis": [
        {
          "name": "Fascioliasis",
          "code": "B66.3"
        }
      ]
    },
    "drug": {
      "fdaDrug": [
        {
          "name": "PIMOZIDE",
          "tradeName": "ORAP FORTE TAB 4 MG",
          "strengthValue": "4",
          "packageType": "Blister",
          "packageSize": "20",
          "dosage": "2",
          "dosageUnit": "capsule",
          "routeOfAdministration": "oral",
          "dosageForm": "tablet",
          "frequency": "Four times daily",
          "duration": 5,
          "specialInstructions": null,
          "relationWithFood": "",
          "howToUse": null
        },
        {
          "name": "KETOPROFEN",
          "tradeName": "ORUVAIL S-R CAPS 100 MG",
          "strengthValue": "100",
          "packageType": "Blister",
          "packageSize": "28",
          "dosage": "2",
          "dosageUnit": "tablespoon (10ml)",
          "routeOfAdministration": "oral",
          "dosageForm": "Prolonged-release capsule, hard",
          "frequency": "Four times daily",
          "duration": 6,
          "specialInstructions": null,
          "relationWithFood": "",
          "howToUse": null
        }
      ]
    },
    "lab": {
      "lab": [
        {
          "name": "FIT Test"
        }
      ]
    },
    "doctorReferral": {
      "name": "Gastroenterologist/ Stomach & Bowel Specialist"
    },
    "followUp": [
      {
        "name": "Do Lab Test"
      },
      {
        "name": "Do the required radiation"
      },
      {
        "name": "No Follow-up - Policy Expired"
      }
    ],
    "postCallAnswer": [
      {
        "question": "doctor_notes",
        "answer": "additional note "
      },
      {
        "question": "symptoms",
        "answer": "symptoms  note"
      },
      {
        "question": "diagnosis",
        "answer": "Diagnosis note"
      },
      {
        "question": "fda_drug",
        "answer": "medications note"
      },
      {
        "question": "lab_codes",
        "answer": "Lab note"
      }
    ],
    "dispense": {
      "url": "https://web.altibb.com/prescription/9EK1IhvLIwMC8rw5066cMVZXqs3",
      "pass_code": 5528,
      "qr_code": "https://services.altibbi.com/qr/https%3A%2F%2Fweb.altibb.com%2Fprescription%2F9EK1IhvLIwMC8rw50jEaHIp3cEVRXqs3"
    }
  },
  "datetime": "2023-06-15T09:46:01.764869Z"
}

Delivery​

Common payload fields​

Webhook types​

1- Status update webhooks​

Consultation statuses​

Consultation outcomes​

Notes​

2- Consultation notification webhooks​

accept_consultation​

doctor_no_answer​

doctor_waiting_the_patient​

voip_notification​

convert_voip_to_gsm_notification​

video_notification​

chat_notification​

chat_history_notification​

3- Recommendation webhooks​