HIS Webhook: Event Notifications to Buktor

HIS Webhook: Sending Data to Buktor

1. Introduction

The HIS Webhook enables Hospital Information Systems (HIS) to send structured data to Buktor for real-time updates. This integration ensures that HIS-generated events (appointments, payments, schedules, etc.) are seamlessly transmitted and processed in Buktor.

2. Webhook API Endpoint

Buktor verifies the Bearer token and the signature of the received data before processing the request.

** Endpoint**

POST https://api.buktor.com/his/receive

** Headers**

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <access_token>"
}

** Sample Request (From HIS to Buktor)**

{
  "event_id": "evt_123456",
  "timestamp": "2025-01-08T12:00:00Z",
  "type": "appointment.created",
  "operation": "created",
  "data": {
    "his_appointment_id": "A123",
    "his_patient_id": "P456",
    "his_doctor_id": "D789",
    "his_status": "confirmed",
    "his_created_at": "2025-03-02T10:30:45"
  },
  "source": "HIS"
}

** Sample Response (Success)**

{
  "status": "success",
  "message": "Data received and processed successfully."
}

** Sample Response (Error - No Mapping Found)**

{
  "status": "error",
  "message": "No mapping found for event_type 'appointment.created' and Client-ID 1001."
}

3. Supported Events

The webhook supports multiple event types from HIS, mapped dynamically to Buktor’s database tables and fields.

| Event Type | Operation | |---------------------------|--------------------|---------------------|------------| | location.created | created | | location.updated | updated | | location.deleted | deleted | | service.created | created | | service.updated | updated | | service.deleted | deleted | | appointment.created | created | | appointment.updated | updated | | appointment.deleted | deleted | | schedule.created | created | | schedule.updated | updated | | schedule.deleted | deleted | | payment.successful | successful | | payment.failed | failed |

4. JSON Mapping for Each Client

Each Buktor client has custom field mappings to transform HIS data into Buktor-compatible data before storage.

** Sample Mapping (his-json-mapping.json)**

{
  "clients": {
    "1001": {
      "mappings": {
        "appointment.created": {
          "fields": {
            "his_appointment_id": "buktor_appointment_id",
            "his_patient_id": "buktor_patient_id",
            "his_doctor_id": "buktor_doctor_id",
            "his_status": "buktor_status",
            "his_created_at": "buktor_created_at"
          }
        }
      }
    }
  }
}

5. Error Handling & Retries

ScenarioExpected Behavior
Valid HIS data with mappingProcess & store data
No JSON mapping found for Client-IDReturn error
Invalid JSON request bodyReturn 400 Bad Request
Database connectivity issueReturn 500 Internal Server Error
Client endpoint unavailableRetry with exponential backoff

6. Idempotency & Signature Verification

Each event includes a unique event_id to prevent duplicate processing. Clients should store processed event_ids to avoid reprocessing the same event.

** Signature Generation (HMAC-SHA256)**

Clients should verify the Buktor-Signature included in the request headers.

Example Code (Node.js)

const crypto = require('crypto');
 
const secret = 'your_shared_secret';
const payload = JSON.stringify({ /* webhook payload */ });
 
const signature = crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');
 
console.log('Buktor-Signature:', signature);

7. Deployment & Testing

** Deploying Webhook**

  • Bearer tokens for authentication can be generated from the Buktor Pro app.
  • Ensure HIS is configured to send events to POST /his-receive.
  • Update firewall rules if necessary.
  • Ensure HIS is configured to send events to POST /his-receive.
  • Update firewall rules if necessary.

** Testing with cURL**

Send a Test Appointment Event

curl -X POST "https://api.buktor.com/his/receive" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <access_token>" \
     -d '{"event_type": "appointment.created", "his_appointment_id": "A123", "his_patient_id": "P456", "his_doctor_id": "D789", "his_status": "confirmed", "his_created_at": "2025-03-02T10:30:45"}'

Expected Response:

{
  "status": "success",
  "message": "Data received and processed successfully."
}

8. Conclusion

  • HIS can now send real-time data updates to Buktor.
  • Each client has its own mapping for seamless data transformation.
  • The system automatically processes and stores incoming data efficiently.
Buktor Webhook: Event Notifications to HISOn-Demand API Calls