@zsign/embed

Vanilla JS helper that mounts a zSign signing session in an iframe and listens for origin-guarded postMessage events from the signing page.

Requires Node 18+. Zero runtime dependencies.

For the React wrapper, see @zsign/react. The task-oriented walkthrough lives in the embed guide.

Install

npm install @zsign/embed

Allow the embedder origin first

Embedding is default-deny. A framed signing page refuses to render unless its parent origin is registered on the envelope owner's account:

curl -X PUT "$ZSIGN_BASE_URL/api/branding/embed-origins" \
  -H "Authorization: Bearer $ZSIGN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origins": ["https://app.yourcompany.com"]}'

ZSIGN_BASE_URL defaults to the public zSign API host.

Or Settings → Embedding in the dashboard. Exact match only, https required except http://localhost[:port], no paths or wildcards, max 10.

Usage

import { createSigningEmbed } from "@zsign/embed";

const handle = createSigningEmbed({
  signingUrl: "https://app.example.com/sign/<token>",
  container: document.getElementById("signing"),
  height: "auto",
  onReady: () => console.log("ready"),
  onSigned: ({ session_id }) => console.log("signed", session_id),
  onError: ({ message }) => console.error(message),
});

// Later:
handle.destroy();

signingUrl is a recipient signing link from POST /api/v1/documents/send (signing_urls) or the dashboard.

Events

The iframe posts { v: 1, type, payload } to the parent. The SDK only accepts messages whose event.origin matches the signing URL origin and whose event.source is the iframe window.

| type | callback | payload | Emitted by the live signing page when | | --- | --- | --- | --- | | zsign:ready | onReady | — | the session has loaded and framing is allowed | | zsign:signed | onSigned | { session_id? } | the signer completes the document | | zsign:error | onError | { message? } | completion fails | | zsign:resize | (iframe height) | { height } | the document body resizes (height: "auto" or omitted) | | zsign:declined | onDeclined | — | the iframe messenger type includes this event; listen for it |

Do not invent other event names. The protocol is v: 1 only.

Options

| Option | Type | Notes | | --- | --- | --- | | signingUrl | string | Required. Full signing-page URL. | | container | HTMLElement | Required. The iframe is appended here. | | height | number \| "auto" | Pixel height, or "auto" / omitted to follow zsign:resize. Default rendered height is 600px until a resize arrives. | | onReady | () => void | | | onSigned | (payload: { session_id?: string }) => void | | | onDeclined | () => void | | | onError | (payload: { message?: string }) => void | |

destroy() removes the iframe and the message listener.