စနစ်လှုပ်ရှားမှု အခြေပြု Webhooks API နှင့် ချိတ်ဆက်မှုများ

Medaius စနစ်သည် စနစ်လှုပ်ရှားမှု အခြေပြု (Event-Driven) Webhooks စနစ် ကို ပံ့ပိုးပေးထားပြီး ဆေးရုံ၊ ဆေးခန်းများနှင့် ဆက်စပ်နေသော ပြင်ပဆော့ဖ်ဝဲလ်စနစ်များ — ဥပမာ ဓာတ်ခွဲခန်းစနစ်များ (LIMS)၊ ပြင်ပဆေးဆိုင်စနစ်များ၊ စာရင်းကိုင် ERP များနှင့် အလိုအလျောက် လူနာထံ SMS ပေးပို့သော စနစ်များ — သို့ လုံခြုံစိတ်ချရသော စာဝှက်စနစ်ဖြင့် အတည်ပြုထားသည့် HTTPS payloads များကို အချိန်နှင့်တပြေးညီ အလိုအလျောက် ပေးပို့နိုင်စေပါသည်။

⚠️ Webhooks ကဏ္ဍသည် Admin အောက်တွင် ပေါ်လာစေရန်အတွက် ပထမဦးစွာ Marketplace တွင် Webhooks မော်ဂျူးကို ဖွင့်ထားရန် လိုအပ်ပါသည် — ဆေးခန်းသုံး မော်ဂျူးများနှင့် တိုးချဲ့စနစ်များ စီမံခန့်ခွဲမှု တွင် ကြည့်ရှုပါ။

၁။ Webhook ချိတ်ဆက်မှု အသစ်တစ်ခု စာရင်းသွင်းခြင်း

1. Admin → Webhooks (/admin?section=webhooks) သို့ သွားပါ။
2. Webhook စာရင်း၏ ညာဘက်အပေါ်ထောင့်ရှိ Add ကို နှိပ်ပါ (စာရင်းမရှိသေးပါက Add Webhook ကို နှိပ်ပါ)။
3. လိုအပ်သော အချက်အလက်များကို ဖြည့်စွက်ပါ:
   • Webhook Name — ချိတ်ဆက်မှု ဖော်ပြချက်အမည် (ဥပမာ- Make.com Patient Sync)။
   • Endpoint URL — အချက်အလက်များ လက်ခံမည့် သင့်ဆာဗာ၏ ဝဘ်လိပ်စာ။ https:// ဖြင့် စတင်ရပါမည်။
   • Description (စိတ်ကြိုက်) — ဤ webhook ၏ ရည်ရွယ်ချက် မှတ်ချက်။
   • Subscribe to Events — လက်ခံလိုသော ဖြစ်ရပ်များကို အမှန်ခြစ်ပါ (သို့မဟုတ် Select All / Deselect All ကို အသုံးပြုပါ)။ အနည်းဆုံး ဖြစ်ရပ်တစ်ခု ရွေးချယ်ရန် လိုအပ်ပါသည်။ လက်ရှိ ပံ့ပိုးပေးထားသော ဖြစ်ရပ်များ:

4. Register Webhook ကို နှိပ်ပါ။ စနစ်က သင့်အတွက် Signing Secret ကို တစ်ကြိမ်သာ ပြသသည့် ဘန်နာဖြင့် ဖော်ပြပေးမည်ဖြစ်ပြီး Copy ကို နှိပ်၍ လုံခြုံစွာ သိမ်းဆည်းထားပါ (နောင်တွင် ထပ်မံပြသမည် မဟုတ်ပါ)။

၂။ HMAC SHA-256 စာဝှက်လက်မှတ် စစ်ဆေးခြင်း (Signature Verification)

ရောက်ရှိလာသော Webhook payloads များသည် Medaius မှ အမှန်တကယ် ပေးပို့ခြင်းဖြစ်ပြီး လမ်းခရီးတွင် ကြားဖြတ်ပြင်ဆင်ထားခြင်း သို့မဟုတ် အတုအယောင် လုပ်ဆောင်ထားခြင်း မရှိစေရန်-

၁။ လျှို့ဝှက်ကုဒ် (Secret Key)

Webhook စာရင်းသွင်းမှု ပြုလုပ်ပြီးသည်နှင့် Medaius သည် ၆၄ လုံးပါ hexadecimal secret တစ်ခုကို ထုတ်ပေးပါသည် (ဖန်တီးပြီးစ banner တွင် တစ်ကြိမ်သာ ပြသပါသည်)။ ဤကုဒ်ကို သင်၏ လက်ခံဆာဗာတွင် လုံခြုံစွာ ထားရှိရပါမည်။

၂။ လက်မှတ် ပါဝင်သော Headers

ပေးပို့မှုတိုင်းတွင် Headers ၃ ခု ပါဝင်ပါသည်-

X-Medaius-Event: patient.created
X-Medaius-Timestamp: 1735689600
X-Medaius-Signature: a3f5b90214c78d4e92b8d0354117a1...

Signature သည် "{timestamp}.{raw_body}" (timestamp တန်ဖိုး၊ အစက် .၊ ထို့နောက် အတိအကျ payload body) ကို secret ဖြင့် HMAC SHA-256 hex digest တွက်ချက်ထားခြင်းဖြစ်ပါသည်။ စစ်ဆေးသည့်အခါ အဆိုပါ ပေါင်းစပ်ထားသော စာသားဖြင့် စစ်ဆေးရမည်ဖြစ်ပြီး raw body သီးသန့်ဖြင့် စစ်ဆေးပါက လက်မှတ် မည်သည့်အခါမျှ ကိုက်ညီမည် မဟုတ်ပါ။

၃။ မိမိဆာဗာဘက်မှ စစ်ဆေးနည်း နမူနာ (Node.js & Python)

// Node.js / Express စစ်ဆေးနည်း နမူနာ
const crypto = require('crypto');

function verifyMedaiusSignature(rawBody, timestampHeader, signatureHeader, webhookSecret) {
  const signedPayload = `${timestampHeader}.${rawBody}`;
  const computedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(signedPayload, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(computedSignature, 'hex'),
    Buffer.from(signatureHeader, 'hex')
  );
}

# Python / FastAPI စစ်ဆေးနည်း နမူနာ
import hmac
import hashlib

def verify_medaius_signature(raw_body: bytes, timestamp_header: str, signature_header: str, webhook_secret: str) -> bool:
    signed_payload = f"{timestamp_header}.{raw_body.decode('utf-8')}".encode('utf-8')
    computed_signature = hmac.new(
        webhook_secret.encode('utf-8'),
        signed_payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(computed_signature, signature_header)

၃။ ချိတ်ဆက်မှု စမ်းသပ်ခြင်း (Test Ping) နှင့် ပေးပို့မှု မှတ်တမ်းများ (Delivery Auditing)

ချိတ်ဆက်မှု စမ်းသပ်ခြင်း (Testing Endpoint Connectivity)

1. Webhooks မျက်နှာပြင်၏ ဘယ်ဘက်စာရင်းရှိ သက်ဆိုင်ရာ webhook ကို ရှာပါ။
2. ၎င်းကတ်ပြားပေါ်ရှိ Test Ping ခလုတ်ကို နှိပ်ပါ။ Medaius က စမ်းသပ် payload တစ်ခုကို ချက်ချင်းပေးပို့ပြီး သင့်ဆာဗာက HTTP 200 OK ဖြင့် တုံ့ပြန်မှု ရှိမရှိ အစီရင်ခံ ပြသပေးမည်ဖြစ်ပါသည်။

ပေးပို့မှု မှတ်တမ်းများနှင့် အလိုအလျောက် ပြန်လည်ပေးပို့ခြင်း (Delivery Logs & Retry Behavior)

1. စာရင်းထဲမှ မည်သည့် webhook ကိုမဆို နှိပ်၍ ရွေးချယ်ပါ — ညာဘက်ခြမ်းတွင် Delivery Logs panel ပွင့်လာပါမည်။
2. Panel ခေါင်းစဉ်ရှိ refresh icon ကို နှိပ်၍ နောက်ဆုံး ပေးပို့မှုများကို ပြန်လည်ရယူနိုင်ပါသည်။
3. မှတ်တမ်းတစ်ခုချင်းစီ၏ အခြေအနေ (Status)၊ တုံ့ပြန်မှုကြာချိန် (Response Latency) နှင့် ပေးပို့/လက်ခံခဲ့သော အပြည့်အစုံ payload များကို စစ်ဆေးနိုင်ပါသည်။

အကယ်၍ သင့်ဆာဗာ စက်ရပ်နေပါက သို့မဟုတ် non-2xx status ပြန်ပို့ပါက Medaius သည် exponential backoff ဖြင့် အလိုအလျောက် ထပ်မံကြိုးစားပေးပို့ပါသည်: 5s, 10s, 20s, 40s, ထို့နောက် 80s (စုစုပေါင်း ၅ ကြိမ်)။ ၅ ကြိမ်လုံး မအောင်မြင်ပါက အဆိုပါ ပေးပို့မှုကို failed အဖြစ် သတ်မှတ်ပြီး ၅ ကြိမ် ဆက်တိုက် လုံးဝမအောင်မြင်သော dispatches များ ဖြစ်ပေါ်ပါက ဆာဗာပျက်နေသော endpoint က retries များ ဆက်တိုက်မစားစေရန် အဆိုပါ subscription ကို အလိုအလျောက် disable ပြုလုပ်ပေးပါသည်။ Endpoint ပြင်ဆင်ပြီးပါက toggle ခလုတ်မှ ပြန်လည်ဖွင့်နိုင်ပါသည်။

၄။ ဆက်စပ်ဖတ်ရှုရန် လမ်းညွှန်များ