Webhook Payload နှင့် Event Types

နားလည်ထားရမယ့် အချက်

Webhook payload တစ်ခုက provider အလိုက် field name အတိအကျ ကွာနိုင်ပေမယ့် ယေဘုယျပုံစံတစ်ခုတည်းကို လိုက်လေ့ရှိပါတယ် — event type ကို ဖော်ပြတဲ့ field တစ်ခု နဲ့ အဲဒီ event နဲ့ ဆိုင်ရာ အသေးစိတ်တွေ ပါတဲ့ data object တစ်ခု။

ဒါက အရေးကြီးတာက real integration တစ်ခုက event အမျိုးအစားတိုင်းအတွက် သီးခြား URL register မလုပ်လေ့ရှိလို့ပါ။ သင့် endpoint က ဝင်လာတဲ့ request တစ်ခုစီရဲ့ event type ကို ကြည့်ပြီး မှန်ကန်တဲ့ logic ဆီကို route လုပ်ပေးရပါတယ်။

• Event type string တစ်ခုစီကို handle လုပ်မယ့် function ဆီ map လုပ်ပါ။
• မသိသေးတဲ့ event type တွေအတွက် safe default (acknowledge + ignore) ကို fallback ထားပါ။
• Provider က event type အသစ် ထပ်ထည့်လာရင်တောင် endpoint ကို တည်ငြိမ်နေစေပါ။

ရိုးရိုးသားသား ပြောရရင် — event type + data ပုံစံက အများစုမှာ တွေ့ရပေမယ့် universal မဟုတ်ပါဘူး၊ field name တွေလည်း ကွာနိုင်ပါတယ်။ Handler မရေးခင် provider ရဲ့ webhook documentation ကို အမြဲဖတ်ပါ။

ONE ENDPOINT, MULTIPLE EVENT TYPES
----------------------------------
-----
All events arrive at one URL: POST /webhooks/orders

  payment.completed  -----> handlePaymentCompleted()
  payment.failed      -----> handlePaymentFailed()
  user.created          -----> handleUserCreated()
  (anything else)        -----> log it, acknowledge, do not crash

လက်တွေ့ scenario နဲ့ ချိတ်ကြည့်မယ်

အောက်က code က dispatch table သေးသေးလေးတစ်ခု — event type string တွေကို handler function တွေဆီ map လုပ်တဲ့ plain object — ကို တည်ဆောက်ထားပါတယ်။ ဒါက real webhook endpoint အားလုံးနီးပါးမှာ ထပ်ခါထပ်ခါ တွေ့ရမယ့် pattern ပါ။

Payload လေးခု ဝင်လာပါတယ် — payment event နှစ်ခု၊ user အသစ် event တစ်ခု၊ dispatch table က တစ်ခါမှ မမြင်ဖူးတဲ့ event type တစ်ခု။ နောက်ဆုံးတစ်ခုက crash မဖြစ်ဘဲ default response ဆီ ကျဆင်းသွားပါတယ်။

Provider တွေက event type အသစ်တွေ ထပ်ထည့်လာနိုင်ပါတယ်။ မသိတဲ့ type ကို ကျယ်ကျယ်လောင်လောင် fail လုပ်တဲ့ router တစ်ခုက handler တစ်ခုလုံးကို ရပ်တန့်စေနိုင်ပေမယ့်၊ report လုပ်ပြီး ဆက်သွားတဲ့ router ကတော့ တည်ငြိမ်နေပါလိမ့်မယ်။

• Webhook payload တစ်ခုမှာ ပုံမှန်အားဖြင့် event type field တစ်ခုနဲ့ event အလိုက် အသေးစိတ်ပါတဲ့ data object တစ်ခု ပါလေ့ရှိပါတယ်။
• Webhook endpoint တစ်ခုတည်းက event type များစွာကို လက်ခံရလေ့ရှိပြီး တစ်ခုစီကို မှန်ကန်တဲ့ handler ဆီ route လုပ်ပေးရပါတယ်။
• Payload field name အတိအကျတွေက provider တစ်ခုစီအလိုက် မတူညီပါဘူး — အမြဲတမ်း provider ရဲ့ documentation ကို စစ်ဆေးပါ။

အတူတူ စမ်းရေးကြည့်မယ်

const handlers = {
  "payment.completed": (data) => `Order ${data.orderId} marked paid`,
  "payment.failed": (data) => `Order ${data.orderId} marked failed, notifying customer`,
  "user.created": (data) => `Welcome email queued for ${data.email}`
};

function routeWebhookEvents(payloads) {
  return payloads.map((raw) => {
    const event = JSON.parse(raw);
    const handler = handlers[event.type];
    if (!handler) {
      return { type: event.type, result: "No handler registered, ignored" };
    }
    return { type: event.type, result: handler(event.data) };
  });
}

const incomingBatch = [
  JSON.stringify({ type: "payment.completed", data: { orderId: "ord_100" } }),
  JSON.stringify({ type: "payment.failed", data: { orderId: "ord_101" } }),
  JSON.stringify({ type: "user.created", data: { email: "mia@example.com" } }),
  JSON.stringify({ type: "invoice.paid", data: { invoiceId: "inv_9" } })
];

console.log(routeWebhookEvents(incomingBatch));

[
  { type: 'payment.completed', result: 'Order ord_100 marked paid' },
  {
    type: 'payment.failed',
    result: 'Order ord_101 marked failed, notifying customer'
  },
  {
    type: 'user.created',
    result: 'Welcome email queued for mia@example.com'
  },
  { type: 'invoice.paid', result: 'No handler registered, ignored' }
]

GitHub Docs — Webhook events and payloads — API Integration & Webhooks