Webhooks

Delivery

Set a callback_url when creating an invoice. On each status transition, swp.gg POSTs JSON with header X-Swp-Signature: sha256=<hex> and User-Agent: swp.gg-webhooks/1.0.

Signature

Verify with HMAC-SHA256(rawBody, secret) where secret is the full whsec_… string from the dashboard (API Keys → Webhook signing secret → Reveal). Use that value as the HMAC key — do not add another whsec_ prefix.

const crypto = require("crypto");

function verifyWebhook(rawBody, header, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  const received = header.replace("sha256=", "");
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(received, "hex"),
  );
}

Events

• invoice.confirming — payment seen on-chain; waiting for confirmations
• invoice.paid — confirmed within accuracy and credited
• invoice.partially_paid — confirmed but below the due amount
• invoice.expired — lifetime ended without a full payment

Payload fields include track_id, status, order_id, amounts, pay_currency, address, tx_hash, and confirmation counts.

Reliability

Delivery is best-effort (~8s timeout, no automatic retries). Make your endpoint idempotent and reconcile with GET /api/v1/invoice/{track_id}?refresh=1 when needed.

Full field reference: API documentation.