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_payment | invoice ပိတ်ပြီးနောက် ငွေရောက်လာသည် (data တွင် payment)၊ status မပြောင်း |
payment.detected / payment.confirmed / payment.orphaned | on-chain ငွေပေးချေမှုတိုင်း (orphaned = reorg ကြောင့် ပျက်သွား)။ customer deposit လိပ်စာ သို့ ငွေပေးချေမှုများတွင် customer_id နှင့် address_id ပါသည် — payment.confirmed တွင် customer ထံ ထည့်ပါ |
withdrawal.* | endpoint တွင် တိုက်ရိုက် ရွေးထားမှသာ ("all events" တွင် မပါ) |
ping | dashboard / CLI ၏ "Send test" ခလုတ် |
လက်ခံသူ (receiver) အတွက် စည်းမျဉ်းများ
- Signature ကို raw body ပေါ်တွင် စစ်ပါ (JSON parse မလုပ်မီ):
hex(HMAC_SHA256(secret, "<Polysia-Timestamp>.<raw body>"))သည်v1=တန်ဖိုးများထဲမှ တစ်ခုနှင့် တူရမည်။ Constant time ဖြင့် နှိုင်းယှဉ်ပါ။ - Timestamp ဟောင်းများကို ငြင်းပါ:
|now − Polysia-Timestamp| > 300 s→ 400 (replay ကာကွယ်ရန်)။ Polysia-Event-Id(= body ၏id) ဖြင့် ထပ်နေခြင်းကို ဖယ်ပါ။ ပို့ခြင်းသည် အနည်းဆုံး တစ်ကြိမ် ဖြစ်သည် — event တူတူ နှစ်ခါ ရောက်နိုင်သည် (timeout ပြီးနောက် ပြန်ပို့ခြင်း၊ လက်ဖြင့် Resend)။ ပြန်ပို့ခြင်းတိုင်းတွင် event id နှင့် body တူတူ ဖြစ်ပြီး timestamp နှင့် signature သာ အသစ်ဖြစ်သည်။- အစဉ်ကို အာမမခံပါ။
invoice.paidသည်invoice.detectedမတိုင်မီ ရောက်နိုင်သည်၊ ပြန်ပို့သော event ဟောင်းသည် အသစ်ထက် နောက်ကျ ရောက်နိုင်သည်။ အစဉ်မှ အခြေအနေကို ဘယ်တော့မှ မဆုံးဖြတ်ပါနှင့် —data.statusအပေါ် ဆောင်ရွက်ပါ၊ သို့မဟုတ်GET /v1/invoices/{id}ကို ခေါ်ပြီး ပြန်လာသည့်အတိုင်း ဆောင်ရွက်ပါ။paidကို နောက်ဆုံးအဖြစ် သတ်မှတ်ပါ (ဘယ်တော့မှ ပြန်မပြောင်း)။ - ၁၀ စက္ကန့်အတွင်း 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 ကို ပိတ်သည် (alertwebhook_failing)။ - Public လိပ်စာပေါ်ရှိ HTTPS သာ (private / loopback / metadata လိပ်စာများကို DNS resolve ပြီးနောက်တွင်လည်း ငြင်းသည်)။
- 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= valuePython (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 ဖြင့်)။