uNode DocsOverviewGuidesAPI referenceConsole ↗

Webhooks

Receive signed notifications when payments settle or server operations finish.

Subscribe

Create a subscription in the console or with POST /v1/webhooks. Use a public HTTPS endpoint and select the events you need. Save the returned secret securely.

{
  "name": "uSwap orders",
  "url": "https://your-service.example/unode-events",
  "event_types": ["server.operation_succeeded", "server.operation_failed", "payment.credited"]
}

Verify before parsing

The header x-unode-signature is sha256= followed by the hexadecimal HMAC-SHA256 of the exact raw request body using your subscription secret. Compare signatures in constant time. Do not reserialize JSON before verification.

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, signature, secret) {
  if (!/^sha256=[a-f0-9]{64}$/.test(signature ?? "")) return false;
  const expected = createHmac("sha256", secret).update(rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(signature.slice(7), "hex"));
}

UNode also sends x-unode-event and x-unode-delivery-id. Deduplicate using the signed payload's event_id. Retries or replays can have another delivery ID; delivery order is not guaranteed.

Handle reliably

Save the verified event durably before returning 2xx. Fetch the current server, operation or balance from the API before delivering a VPS or issuing a refund. A webhook is a notification, not authorization from your customer. Keep polling as recovery.

Inspect delivery attempts, send a test event, or replay a failed delivery from the console. To rotate the signing secret, replace the subscription. See the API reference for all supported events and delivery endpoints.