Polysia webhooks — merchant guide
Polysia POSTs a signed JSON event to your HTTPS endpoint when something happens to an invoice or payment. Endpoints are added in the dashboard (API → Webhooks, business admin) or with polysiad webhook add -business ID -url https://…; the signing secret (whsec_…) is shown once.
အကျဉ်းချုပ် (မြန်မာ): Raw body + timestamp ကို HMAC-SHA256 နဲ့ စစ်ပါ (5 မိနစ်ထက်ဟောင်းရင် ငြင်း)၊ Polysia-Event-Id နဲ့ dedupe လုပ်ပါ၊ 2xx ကို 10 s အတွင်း ပြန်ပါ။ Event အစဉ်ကို အာမ မခံပါ — data.status (သို့) GET /v1/invoices/{id} ကိုပဲ ယုံပါ။ Retry / Resend မှာ event id မပြောင်းပါ (timestamp နဲ့ signature ပဲ အသစ်)။
The 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 is the object GET /v1/invoices/{id} (or GET /v1/payments/{id}) returned at the moment of the event, plus excess / missing / payment on the events noted below. An invoice event embeds at most the 20 newest payments; with more, payments_truncated: true and payments_total are set — use GET /v1/payments?invoice=inv_… for the full list. By the time you process it the invoice may have moved on — use GET for the current state.
Events
| Type | When |
|---|---|
invoice.detected | First payment to an open invoice seen (not final yet — do not ship) |
invoice.paid | Finalized total ≥ amount (− your underpay tolerance) — ship on this |
invoice.overpaid | Paid with an excess (excess in data) |
invoice.underpaid | Closed at expiry with a partial payment (missing in data) — final |
invoice.expired | Closed with nothing received |
invoice.cancelled | You cancelled it (POST /v1/invoices/{id}/cancel) |
invoice.late_payment | Money arrived after the invoice closed (payment in data); status unchanged |
payment.detected / payment.confirmed / payment.orphaned | Every on-chain payment (orphaned = removed by a reorg). Payments to a customer deposit address carry customer_id and address_id — credit the customer on payment.confirmed |
withdrawal.* | Only if the endpoint lists them explicitly (not part of "all events") |
ping | The dashboard / CLI "Send test" button |
Rules for your receiver
- Verify the signature over the raw body (before any JSON parsing):
hex(HMAC_SHA256(secret, "<Polysia-Timestamp>.<raw body>"))must equal one of the
v1=values. Compare in constant time. - Reject old timestamps:
|now − Polysia-Timestamp| > 300 s→ 400 (replay protection). - Deduplicate on
Polysia-Event-Id(= bodyid). Delivery is at-least-once: the same event can arrive twice(retry after a timeout, manual Resend). Retries and resends keep the same event id and the same body; only the timestamp and the signature are new.
- Order is not guaranteed.
invoice.paidcan arrive beforeinvoice.detected, a retried old event after a newerone. Never derive state from the order: act on
data.status, or callGET /v1/invoices/{id}and act on what it returns. Treatpaidas final (it is never reverted). - Answer 2xx within 10 s (the body of a 2xx answer is ignored and not stored; for errors the first 1 KB is kept
in the delivery log — never echo secrets or customer data), then do slow work (e-mails, fulfilment) asynchronously. Anything else — 3xx (redirects are not followed), 4xx, 5xx, timeouts, TLS errors — is retried: after 1 m, 5 m, 15 m, 1 h, 3 h, 6 h, 12 h, 24 h, 24 h (±10 %), i.e. about 3 days, then the delivery is
failed(Resend from the dashboard delivery log). An endpoint that fails everything for 3 days is disabled (alertwebhook_failing). - HTTPS on a public address only (private / loopback / metadata addresses are refused, also after DNS resolution).
- Rotation: "Rotate secret" gives a new secret; for 24 h both secrets sign (two
v1=values) — deploy the new secretwithin that window. One rotation at a time: a second one is refused until the 24 h overlap ended (to cut an old secret off at once, disable the endpoint and add a new one).
Examples
The Python receiver and the openssl command were run against Polysia-signed requests (2026-11-18). The Node and PHP snippets follow the same algorithm but were not executed in this repository (no Node/PHP on the build machine) — test them with the dashboard's "Send test" before relying on them.
Shell / openssl (check a captured request):
printf '%s' "$TS.$(cat body.json)" | openssl dgst -sha256 -hmac "$POLYSIA_WEBHOOK_SECRET" -hex # = the v1= value
Python (stdlib): polysia_webhook_receiver.py — complete receiver with verification, 5-minute window and de-duplication.
Node.js (Express) — keep the 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']
Testing locally
Polysia refuses http:// and local addresses unless the server sets WEBHOOK_ALLOW_HTTP=1 (http to localhost) or WEBHOOK_ALLOW_PRIVATE=1 (LAN). Use them only for tests; the step-by-step local test is the local receiver above.