docs
On this page

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.

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

TypeWhen
invoice.detectedFirst payment to an open invoice seen (not final yet — do not ship)
invoice.paidFinalized total ≥ amount (− your underpay tolerance) — ship on this
invoice.overpaidPaid with an excess (excess in data)
invoice.underpaidClosed at expiry with a partial payment (missing in data) — final
invoice.expiredClosed with nothing received
invoice.cancelledYou cancelled it (POST /v1/invoices/{id}/cancel)
invoice.late_paymentMoney arrived after the invoice closed (payment in data); status unchanged
payment.detected / payment.confirmed / payment.orphanedEvery 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")
pingThe dashboard / CLI "Send test" button

Rules for your receiver

  1. 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.
  2. Reject old timestamps: |now − Polysia-Timestamp| > 300 s → 400 (replay protection).
  3. Deduplicate on Polysia-Event-Id (= body id). 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.
  4. Order is not guaranteed. invoice.paid can arrive before invoice.detected, a retried old event after a newer one. Never derive state from the order: act on data.status, or call GET /v1/invoices/{id} and act on what it returns. Treat paid as final (it is never reverted).
  5. 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 (alert webhook_failing).
  6. HTTPS on a public address only (private / loopback / metadata addresses are refused, also after DNS resolution).
  7. Rotation: "Rotate secret" gives a new secret; for 24 h both secrets sign (two v1= values) — deploy the new secret within 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 (for example with the Python receiver above).