Every render call is a render request with its own id (rnd_…), returned as renderId by POST /v1/templates/:id/render. A request holds its files in page order, the exact design it was rendered from (after your modifications) and where it came from. That stored design is what lets you re-render a request later, or let your users edit it in the embedded editor, without touching the master template.

The editor talks to your page with postMessage, sent only to the origin you gave when creating the session — never to *. Check event.origin on your side too.

The editor has its own Save button. To save from your own UI instead, post { type: "frameline:render:save" } to the iframe; it is accepted only from the parent page at the session's origin.

const EDITOR_ORIGIN = "https://buildonce.app";
const iframe = document.querySelector("#editor");
iframe.src = editorUrl; // from your server

window.addEventListener("message", (event) => {
  if (event.origin !== EDITOR_ORIGIN) return;
  const message = event.data;
  switch (message.type) {
    case "frameline:render:change":
      setUnsaved(message.dirty);
      break;
    case "frameline:render:saved":
      showImages(message.files.map((file) => file.url));
      rememberRender(message.renderId); // edit this one next time
      break;
    case "frameline:render:error":
      showError(message.message);
      break;
  }
});

saveButton.onclick = () =>
  iframe.contentWindow.postMessage({ type: "frameline:render:save" }, EDITOR_ORIGIN);

Every save that changed something is also sent to the webhook endpoints subscribed to render.edited (Settings → Webhooks) — the reliable record even if the user closed the page before the message arrived. The data is the same object as the saved message, plus the embedId. Failed deliveries are retried.

BuildOnce-Event: render.edited
BuildOnce-Delivery-Id: whd_6tq2k9m4xa1b
BuildOnce-Signature: t=1790606243,v1=5f0c…e91a

{
  "id": "evt_8m2kq4x7tb1c",
  "type": "render.edited",
  "created_at": "2026-09-28T12:05:00.000Z",
  "workspace_id": "ws_123",
  "data": {
    "sessionId": "res_2mf8a0c4pq9d",
    "renderId": "rnd_3bx8tsv9emk3",
    "sourceRenderId": "rnd_8kq2m4x7ab1c",
    "sourceTemplateId": "tpl_123",
    "embedId": "emb_123",
    "files": [{ "pageId": "s1", "url": "https://…", "width": 1080, "height": 1350 }],
    "credits": { "charged": 4, "balanceAfter": 1873 }
  }
}

Verify every delivery with the endpoint's signing secret (whsec_…, shown once when you add or rotate the endpoint under Settings → Webhooks): v1 must equal HMAC-SHA256 of t + "." + rawBody. Use the raw request body, not a re-serialised one, and reject old timestamps to stop replays.

import crypto from "node:crypto";

function verify(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) <= toleranceSeconds;
  return (
    fresh &&
    typeof parts.v1 === "string" &&
    parts.v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  );
}

• 1 credit per image, on every request — a carousel of 4 slides costs 4.
• A PDF costs 1 credit per page.
• A request identical to an earlier one is still a new request and is still charged; its files are served from storage, not drawn again.
• A retry with the same idempotencyKey returns the original request and costs 0.
• An editor save with no changes costs 0 and returns the current request (unchanged: true). A save that changed one slide renders — and charges for — every slide, because it is a complete new request.

• Files always match the design: same number, same order. A page with nothing on it renders as a blank image with isEmpty: true — it is never silently skipped.
• Slides added, removed or reordered in the editor come back that way in the new request's files.
• Set a value on one slide with a page-scoped key: page2@headline (by position, from 1) or s2@headline (by page id). A page id beats a position, which beats a plain headline. Works on template renders and rerenders.

{
  "headline": "Used on every slide without its own value",
  "page1@headline": "Slide one",
  "s3@headline": "The slide whose id is s3"
}