docs
ဤစာမျက်နှာတွင်

Polysia webhook များ — ဆိုင်များအတွက် လမ်းညွှန်

Invoice သို့မဟုတ် payment တစ်ခုခုတွင် ဖြစ်ပျက်မှု ရှိသောအခါ Polysia က sign လုပ်ထားသော JSON event ကို သင့် HTTPS endpoint သို့ POST ပို့သည်။ Endpoint များကို dashboard (API → Webhooks၊ business admin) တွင် သို့မဟုတ် polysiad webhook add -business ID -url https://… ဖြင့် ထည့်ပါ။ Signing secret (whsec_…) ကို တစ်ကြိမ်သာ ပြမည်။

Request

POST https://shop.example.com/polysia/webhook
Content-Type:       application/json
User-Agent:         Polysia-Webhooks/1.0
Polysia-Event-Id:   evt_4f1c…            (same on every retry / resend of this event)
Polysia-Timestamp:  1794940000           (unix seconds of THIS attempt)
Polysia-Signature:  v1=5f2b…             (two values "v1=…,v1=…" for 24 h after a secret rotation)
{
  "id": "evt_4f1c…", "object": "event", "type": "invoice.paid", "created": 1794939990,
  "api_version": "2026-11-18", "business_id": "0x5e8b…", "livemode": true,
  "data": { "object": "invoice", "id": "inv_…", "status": "paid", "amount": "25.000000", "received": "25.000000",
            "address": "0x…", "order_id": "A-1042", "metadata": {}, "payments": [ { "object": "payment", "id": "pay_…", … } ], … }
}

data သည် event ဖြစ်ချိန်တွင် GET /v1/invoices/{id} (သို့မဟုတ် GET /v1/payments/{id}) ပြန်ပေးမည့် object ဖြစ်ပြီး အောက်တွင် ဖော်ပြထားသော event များတွင် excess / missing / payment ပါ ထပ်ပါသည်။ Invoice event တစ်ခုတွင် အသစ်ဆုံး ၂၀ ခုအထိသာ payment များ ပါသည်။ ထို့ထက်များလျှင် payments_truncated: true နှင့် payments_total ပါမည် — စာရင်းအပြည့်အတွက် GET /v1/payments?invoice=inv_… ကို သုံးပါ။ သင် process လုပ်ချိန်တွင် invoice သည် ရှေ့ဆက်ပြောင်းသွားပြီး ဖြစ်နိုင်သည် — လက်ရှိ အခြေအနေအတွက် GET ကို သုံးပါ။

Event များ

Typeဘယ်အချိန်
invoice.detectedဖွင့်ထားသော invoice သို့ ပထမဆုံး ငွေပေးချေမှု တွေ့ပြီ (မအတည်သေး — ပစ္စည်း မပို့ပါနှင့်)
invoice.paidအတည်ပြုပြီး စုစုပေါင်း ≥ amount (− သင့် underpay tolerance) — ဤ event တွင် ပစ္စည်းပို့ပါ
invoice.overpaidပိုလျှံ၍ ပေးချေခဲ့သည် (data တွင် excess)
invoice.underpaidသက်တမ်းကုန်ချိန်တွင် တစ်စိတ်တစ်ပိုင်း ငွေပေးချေမှုဖြင့် ပိတ်သည် (data တွင် missing) — နောက်ဆုံး
invoice.expiredဘာမှ မရဘဲ ပိတ်သည်
invoice.cancelledသင် ပယ်ဖျက်ခဲ့သည် (POST /v1/invoices/{id}/cancel)
invoice.late_paymentinvoice ပိတ်ပြီးနောက် ငွေရောက်လာသည် (data တွင် payment)၊ status မပြောင်း
payment.detected / payment.confirmed / payment.orphanedon-chain ငွေပေးချေမှုတိုင်း (orphaned = reorg ကြောင့် ပျက်သွား)။ customer deposit လိပ်စာ သို့ ငွေပေးချေမှုများတွင် customer_id နှင့် address_id ပါသည် — payment.confirmed တွင် customer ထံ ထည့်ပါ
withdrawal.*endpoint တွင် တိုက်ရိုက် ရွေးထားမှသာ ("all events" တွင် မပါ)
pingdashboard / CLI ၏ "Send test" ခလုတ်

လက်ခံသူ (receiver) အတွက် စည်းမျဉ်းများ

  1. Signature ကို raw body ပေါ်တွင် စစ်ပါ (JSON parse မလုပ်မီ): hex(HMAC_SHA256(secret, "<Polysia-Timestamp>.<raw body>")) သည် v1= တန်ဖိုးများထဲမှ တစ်ခုနှင့် တူရမည်။ Constant time ဖြင့် နှိုင်းယှဉ်ပါ။
  2. Timestamp ဟောင်းများကို ငြင်းပါ: |now − Polysia-Timestamp| > 300 s → 400 (replay ကာကွယ်ရန်)။
  3. Polysia-Event-Id (= body ၏ id) ဖြင့် ထပ်နေခြင်းကို ဖယ်ပါ။ ပို့ခြင်းသည် အနည်းဆုံး တစ်ကြိမ် ဖြစ်သည် — event တူတူ နှစ်ခါ ရောက်နိုင်သည် (timeout ပြီးနောက် ပြန်ပို့ခြင်း၊ လက်ဖြင့် Resend)။ ပြန်ပို့ခြင်းတိုင်းတွင် event id နှင့် body တူတူ ဖြစ်ပြီး timestamp နှင့် signature သာ အသစ်ဖြစ်သည်။
  4. အစဉ်ကို အာမမခံပါ။ invoice.paid သည် invoice.detected မတိုင်မီ ရောက်နိုင်သည်၊ ပြန်ပို့သော event ဟောင်းသည် အသစ်ထက် နောက်ကျ ရောက်နိုင်သည်။ အစဉ်မှ အခြေအနေကို ဘယ်တော့မှ မဆုံးဖြတ်ပါနှင့် — data.status အပေါ် ဆောင်ရွက်ပါ၊ သို့မဟုတ် GET /v1/invoices/{id} ကို ခေါ်ပြီး ပြန်လာသည့်အတိုင်း ဆောင်ရွက်ပါ။ paid ကို နောက်ဆုံးအဖြစ် သတ်မှတ်ပါ (ဘယ်တော့မှ ပြန်မပြောင်း)။
  5. ၁၀ စက္ကန့်အတွင်း 2xx ပြန်ပါ (2xx response ၏ body ကို လျစ်လျူရှုပြီး မသိမ်းပါ၊ error များအတွက် ပထမ 1 KB ကို delivery log ထဲ သိမ်းသည် — secret သို့မဟုတ် customer data ကို ဘယ်တော့မှ ပြန်မထုတ်ပါနှင့်)၊ ထို့နောက် နှေးသောအလုပ်များ (email၊ ပစ္စည်းပို့ခြင်း) ကို နောက်ကွယ်တွင် လုပ်ပါ။ အခြားအားလုံး — 3xx (redirect ကို မလိုက်ပါ)၊ 4xx၊ 5xx၊ timeout၊ TLS error — ကို ပြန်ပို့သည်: 1 m၊ 5 m၊ 15 m၊ 1 h၊ 3 h၊ 6 h၊ 12 h၊ 24 h၊ 24 h (±10 %) ပြီးနောက် — ဆိုလိုသည်မှာ ရက် ၃ ရက်ခန့် — ထို့နောက် delivery သည် failed ဖြစ်သည် (dashboard delivery log မှ Resend လုပ်ပါ)။ ရက် ၃ ရက်လုံး အားလုံး မအောင်မြင်သော endpoint ကို ပိတ်သည် (alert webhook_failing)။
  6. Public လိပ်စာပေါ်ရှိ HTTPS သာ (private / loopback / metadata လိပ်စာများကို DNS resolve ပြီးနောက်တွင်လည်း ငြင်းသည်)။
  7. Secret လဲခြင်း: "Rotate secret" က secret အသစ် ပေးသည်။ ၂၄ နာရီကြာ secret နှစ်ခုလုံးဖြင့် sign လုပ်သည် (v1= တန်ဖိုး နှစ်ခု) — ထိုအချိန်အတွင်း secret အသစ်ကို deploy လုပ်ပါ။ တစ်ကြိမ်လျှင် လဲခြင်း တစ်ခုသာ — ၂၄ နာရီ ထပ်နေချိန် မပြီးမချင်း ဒုတိယအကြိမ်ကို ငြင်းသည် (secret ဟောင်းကို ချက်ချင်း ဖြတ်လိုလျှင် endpoint ကို ပိတ်ပြီး အသစ်ထည့်ပါ)။

ဥပမာများ

Python receiver နှင့် openssl command ကို Polysia က sign လုပ်ထားသော request များဖြင့် run ခဲ့သည် (2026-11-18)။ Node နှင့် PHP နမူနာများသည် algorithm တူတူကို လိုက်ထားသော်လည်း run မကြည့်ရသေးပါ (build စက်တွင် Node/PHP မရှိ) — အားမကိုးမီ dashboard ၏ "Send test" ဖြင့် စမ်းပါ။

Shell / openssl (ဖမ်းယူထားသော request ကို စစ်ရန်):

printf '%s' "$TS.$(cat body.json)" | openssl dgst -sha256 -hmac "$POLYSIA_WEBHOOK_SECRET" -hex   # = the v1= value

Python (stdlib): polysia_webhook_receiver.py — စစ်ဆေးခြင်း၊ ၅ မိနစ် အချိန်ကန့်သတ်ချက်နှင့် ထပ်နေခြင်း ဖယ်ရှားခြင်း ပါဝင်သော receiver အပြည့်အစုံ။

Node.js (Express) — raw body ကို ထိန်းထားပါ:

const crypto = require('crypto');
const express = require('express');
const app = express();
const SECRET = process.env.POLYSIA_WEBHOOK_SECRET;
const seen = new Set(); // use your database in production

app.post('/polysia/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('Polysia-Timestamp') || '';
  const header = req.get('Polysia-Signature') || '';
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(400);
  const expected = crypto.createHmac('sha256', SECRET).update(ts + '.').update(req.body).digest('hex');
  const ok = header.split(',').map(s => s.trim()).some(p => p.startsWith('v1=') && p.length === expected.length + 3 &&
    crypto.timingSafeEqual(Buffer.from(p.slice(3)), Buffer.from(expected)));
  if (!ok) return res.sendStatus(400);
  const event = JSON.parse(req.body.toString('utf8'));
  res.sendStatus(200);                       // answer fast
  if (seen.has(event.id)) return;            // duplicate delivery
  seen.add(event.id);
  if (event.type === 'invoice.paid' && event.data.status === 'paid') {
    // mark order event.data.order_id as paid (idempotently); order of events is not guaranteed
  }
});
app.listen(3000);

PHP:

<?php
$secret = getenv('POLYSIA_WEBHOOK_SECRET');
$body   = file_get_contents('php://input');                  // raw body, before json_decode
$ts     = $_SERVER['HTTP_POLYSIA_TIMESTAMP'] ?? '';
$header = $_SERVER['HTTP_POLYSIA_SIGNATURE'] ?? '';
if (!ctype_digit($ts) || abs(time() - (int)$ts) > 300) { http_response_code(400); exit; }
$expected = hash_hmac('sha256', $ts . '.' . $body, $secret);
$ok = false;
foreach (explode(',', $header) as $part) {
    $part = trim($part);
    if (strncmp($part, 'v1=', 3) === 0 && hash_equals($expected, substr($part, 3))) { $ok = true; }
}
if (!$ok) { http_response_code(400); exit; }
$event = json_decode($body, true);
http_response_code(200);
// de-duplicate on $event['id'] (e.g. a UNIQUE column), then act on $event['data']['status']

Local တွင် စမ်းသပ်ခြင်း

Server က WEBHOOK_ALLOW_HTTP=1 (localhost သို့ http) သို့မဟုတ် WEBHOOK_ALLOW_PRIVATE=1 (LAN) မထားလျှင် Polysia သည် http:// နှင့် local လိပ်စာများကို ငြင်းသည်။ စမ်းသပ်ရန်အတွက်သာ သုံးပါ (ဥပမာ အထက်ပါ Python receiver ဖြင့်)။