Webhook Documentation

This document describes the webhook functionality provided by Buktor. Clients can set up webhooks on their HIS/ERP systems to receive real-time notifications when major data updates occur.

1. Authentication

Buktor uses a secret key for authenticating webhook requests. Each request includes an Authorization header with a bearer token and a Buktor-Signature header containing an HMAC-SHA256 hash of the payload.

Request Headers

Content-Type: application/json
Authorization: Bearer <secret_key>
Buktor-Signature: <hashed_signature>

Authorization: Bearer token shared with the client.
Buktor-Signature: HMAC-SHA256 hash of the payload, generated using a shared secret.

2. JSON Payload Structure

General Structure

{
  "event_id": "evt_123456",
  "timestamp": "2025-01-08T12:00:00Z",
  "client_id": "cli_001",
  "type": "schedule.updated",
  "operation": "updated",
  "data": { },
  "source": "Buktor"
}

Fields:

event_id: Unique identifier for the event.
timestamp: Time of the event in ISO 8601 format (UTC).
client_id: Unique identifier for the client.
type: Type of the event (e.g., schedule.updated, service.created).
operation: Operation performed (created, updated, deleted).
data: Event-specific data (structure varies by event type).
source: Source of the event, always set to "Buktor".

3. Updated Sample Payloads

3.1 Schedule Created

{
  "event_id": "evt_67ad91e5b46de",
  "timestamp": "2025-02-13T06:32:05.739072Z",
  "client_id": 296151287157,
  "type": "schedule.created",
  "operation": "created",
  "data": {
    "business_id": 296151287157,
    "business_name": "FutureCare Hospital",
    "service_code": "BA1",
    "service_name": "General Consultation",
    "category_code": "G",
    "location_code": "WTE9",
    "schedule_id": "sched_001",
    "schedule_code": "S",
    "schedule_type": "monthly",
    "schedule_validity_start": "2025-01-10",
    "schedule_validity_end": "2025-05-20",
    "week": "3",
    "day": 2,
    "working_time_start": "06:00",
    "working_time_end": "20:00",
    "time_slots": [
      {
        "session_time": "06:00 - 12:00",
        "slot_time": "06:00-07:00",
        "max_bookings": 4
      }
    ],
    "break_time": "12:00-13:00",
    "created_at": "2025-02-13T05:59:19.894957Z"
  },
  "source": "Buktor"
}

3.2 Holiday Created

{
  "event_id": "evt_67ada949839e4",
  "timestamp": "2025-02-13T08:11:53.539128Z",
  "client_id": 296151287157,
  "type": "holiday.created",
  "operation": "created",
  "data": {
    "business_id": 296151287157,
    "business_name": "FutureCare Hospital",
    "service_code": "BA1",
    "service_name": "General Consultation",
    "category_code": "G",
    "location_code": "WTE9",
    "holiday_id": "hol_001",
    "holiday_date": "2025-02-18",
    "full_holiday": true,
    "partial_holiday": [],
    "created_at": "2025-02-13T08:11:53.533171Z"
  },
  "source": "Buktor"
}

3.3 Holiday Deleted

{
  "event_id": "evt_67adadb1e916b",
  "timestamp": "2025-02-13T08:30:41.954750Z",
  "client_id": 296151287157,
  "type": "holiday.deleted",
  "operation": "delete",
  "data": {
    "business_id": 296151287157,
    "business_name": "FutureCare Hospital",
    "service_code": "BA1",
    "service_name": "General Consultation",
    "category_code": "G",
    "location_code": "WTE9",
    "holiday_id": "hol_001",
    "holiday_date": "2025-02-18"
  },
  "source": "Buktor"
}

3.4 Appointment Created

{
  "event_id": "evt_67ada94c839e5",
  "timestamp": "2025-02-13T08:31:53.539128Z",
  "client_id": 296151287157,
  "type": "appointment.created",
  "operation": "created",
  "data": {
    "business_id": 296151287157,
    "business_name": "FutureCare Hospital",
    "appointment_id": "app_001",
    "service_code": "BA1",
    "service_name": "General Consultation",
    "category_code": "G",
    "location_code": "WTE9",
    "appointment_time": "2025-02-20T10:00:00Z",
    "patient_id": "pat_123",
    "doctor_id": "doc_456",
    "status": "confirmed",
    "created_at": "2025-02-13T08:31:53.533171Z"
  },
  "source": "Buktor"
}

4. Idempotency

Each event has a unique event_id to ensure idempotency. Clients should store processed event_ids to prevent processing the same event multiple times.

5. Error Handling and Retries

If the client’s webhook endpoint returns a non-2xx status code, Buktor will retry the request with exponential backoff for up to 5 attempts. After 5 failed attempts, the event will be marked as failed.

6. Signature Generation

The Buktor-Signature is generated using HMAC-SHA256 with a shared secret.

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. Event Types and Operations

Event Type	Operation (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
holiday.created	created
holiday.deleted	deleted
late_arrival.created	created
late_arrival.deleted	deleted
payment.successful	successful
payment.failed	failed

customer.created | created | | customer.updated | updated

Embedding Buktor Pro App HIS Webhook: Event Notifications to Buktor