Webhooks and billing
NoMac tells your backend when your users' Macs and phones wait for their turn, are ready, ending and ended, when their drives are saved or deleted, and when your credit runs low, with your user's label and what it cost, so you can react and bill your own way.
Make a webhook
const hook = await nomac.webhooks.create({ url: "https://platform.example/nomac" }); // every event
// Keep hook.secret: it is shown once.An https URL at a public address, up to 5 per account. It takes every event unless you name some (events: ["mac.ended", "phone.ended"]). Each event is a JSON POST. A webhook keeps the events it was made with: to take a kind added later, make a new one.
Events
- mac.queued
- A user's Mac has to wait for its turn, and why: your account's limit, the user's drive still on their other Mac, or no Mac free yet.
- mac.ready
- A user's Mac is running, with its label and whether its drive is on it.
- mac.ending_soon
- It stops in about 10 minutes, and why: its time limit, its spend cap or the credit.
- mac.ended
- It ended, with its cost, its reason and whether its drive is still saving.
- drive.saved
- A user's drive was saved, with what changed and the save's charge.
- drive.deleted
- A user's drive was deleted: by you, or after 30 days without a session.
- phone.queued
- A phone has to wait for a free one, up to 5 minutes.
- phone.ready
- A phone is ready, with its label and device.
- phone.ended
- A phone ended, with its cost and reason.
- credit.low
- Your credit covers less than an hour of what runs now: add some before every user's Mac and phone stops at once.
{ "id": "whd_...", "type": "mac.ended", "created_at": "2026-11-11T18:00:00.000Z",
"data": { "reason": "stopped",
"session": { "id": "ses_...", "state": "stopped", "label": "user-42",
"ready_at": "...", "shutdown_at": "...", "failure_code": null,
"drive": { "name": "label/drv_...", "label": "user-42", "saving": true },
"cost": { "currency": "USD", "accrued_microunits": "720000",
"billable_seconds": 2830, "billed_seconds": 2880 } } } }reason is stopped, idle, time_limit, spend_cap, credit, crashed, no_capacity or start_failed, and for a Mac also queue_expired (it waited in line past its queue_seconds) or drive_unavailable (require_drive). Neither of those two is charged.
{ "id": "whd_...", "type": "mac.queued", "created_at": "2026-11-11T18:00:00.000Z",
"data": { "reason": "account_limit", "queue_expires_at": "2026-11-11T18:10:00.000Z",
"session": { "id": "ses_...", "state": "queued", "label": "user-42",
"ready_at": null, "shutdown_at": null, "failure_code": null,
"drive": { "name": "label/drv_...", "label": "user-42", "state": "preparing" },
"cost": { "currency": "USD", "accrued_microunits": "0",
"billable_seconds": 0, "billed_seconds": 0 } } } }mac.queued and phone.queued come only for a start that has to wait, as it is made, so you can show your user that it waits. reason is account_limit (your Macs at once, with queue_seconds), drive (the user's drive is on their other Mac) or capacity (no Mac or phone free yet). Waiting is free. Then comes mac.ready or phone.ready, or, if it has not started by queue_expires_at, mac.ended or phone.ended, with nothing charged. capacity is NoMac's count at the start, so a Mac or phone that frees up can start it seconds later.
Deliveries can arrive out of order, for example a mac.queued your endpoint refused and took on a retry after its mac.ready. Compare created_at and keep the newest state of each session.
Check every delivery
import { verifyWebhook } from "@nomac/sdk";
app.post("/nomac", express.raw({ type: "application/json" }), async (req, res) => {
const event = await verifyWebhook(req.body, req.get("nomac-signature"), process.env.NOMAC_WEBHOOK_SECRET);
if (event.type === "mac.ended" || event.type === "phone.ended") await charge(event.data.session.label, event.data.session.cost);
res.sendStatus(204);
});Pass the raw body as received, not parsed JSON. The nomac-signature header is t=<unix seconds>,v1=<hex HMAC-SHA256 of "t.body" under the secret>, and a signature older than 5 minutes is refused.
- A delivery not answered 2xx within 5 seconds is sent again 1, 2, 4 and up to 60 minutes later, 12 times in all. Redirects are not followed.
- A delivery can arrive more than once: key on its
id, also in thenomac-deliveryheader. webhooks.deliveries(id)lists the last 30 days' deliveries, so you can read back what your endpoint missed while it was down.POST /api/v1/webhooks/{id}/testsends your endpoint a signedwebhook.testevent at once, andPOST /api/v1/webhooks/{id}/deliveries/{delivery}/redeliversends a delivery it has not taken again. Both answer the delivery; the dashboard's Platform page has both.
Bill your users
Each mac.ended and phone.ended carries what you need: the label (your user), billed_seconds (whole minutes, at least one) and accrued_microunits, what NoMac charged your account in millionths of a dollar. Each drive.saved adds its charge_microunits when the user's drive is past your included ones. Charge your user from those, with your own price on top.
To reconcile, list a user's Macs and phones with their cost:
const { macs } = await nomac.macs.list({ label: "user-42" });
const phones = await nomac.phones.list({ label: "user-42" });
const spent = [...macs, ...phones].reduce((sum, s) => sum + Number(s.session.cost?.accrued_microunits ?? 0), 0) / 1e6; // dollarsOr every user at once: GET /api/v1/usage/labels answers each label's Macs and phones, their billed minutes and cost, and its drive's charged saves, most cost first, for this month or ?from= and ?to=. Add ?format=csv for a spreadsheet.