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.