---
title: "Node.js Tutorial: Send, Embed and Track a Contract"
description: "Build a Node.js app that sends a contract, embeds the signing ceremony, verifies webhooks and downloads the signed PDF, with no dependencies."
canonical: "https://signatureapi.com/docs/tutorials/node"
source: "https://signatureapi.com/docs/tutorials/node.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T17:33:13Z"
---

# Node.js Tutorial: Send, Embed and Track a Contract

Build a Node.js app that sends a contract, embeds the signing ceremony, verifies webhooks and downloads the signed PDF, with no dependencies.

_Last verified against API version 1.18.0._

This tutorial builds a complete Node.js app with SignatureAPI: your server creates an envelope, the user signs inside your page, a verified webhook reports the result, and your server downloads the signed PDF. It uses only Node.js built-ins (`node:http`, `fetch`, `node:crypto`), so the same code fits Express, Fastify or any other framework.

The app has one page and four server routes:

- `GET /`: a form and the ceremony iframe.
- `POST /api/contracts`: creates the envelope and returns the ceremony URL.
- `GET /api/contracts/{id}`: reads the envelope status on the server.
- `GET /api/contracts/{id}/signed.pdf`: streams the signed PDF.
- `POST /webhooks/signatureapi`: receives events and verifies each one.

## Before you start

- Node.js 20 or newer.
- A test API key (`key_test_...`) from the [Dashboard](https://dashboard.signatureapi.com). Test envelopes are free, send no emails and are not legally binding. See [Test mode](https://signatureapi.com/docs/api/test-mode).
- To receive webhooks on your machine, a public tunnel to your local port and a webhook endpoint for it in [Dashboard > Settings > Webhooks](https://dashboard.signatureapi.com/settings/webhooks). Copy the endpoint's signing secret. See [Set Up Webhooks](https://signatureapi.com/docs/api/guides/how-to/set-up-webhooks).

## 1. Create the envelope on your server

The API key stays on your server. `buildContract()` builds the envelope with three recipient options for embedding:

- `delivery_type: "none"`: SignatureAPI doesn't email the signed PDF, because your app shows the result.
- [`custom` authentication](https://signatureapi.com/docs/api/resources/ceremonies/authentication/custom): your app already signed the user in, so the ceremony URL comes back in the response instead of an email.
- `embeddable_in`: the origin allowed to show the ceremony in an iframe.

```javascript signatureapi.mjs
export function buildContract({ name, email, userId, appOrigin }) {
  return {
    title: 'Service Agreement',
    metadata: { app_user_id: userId },
    documents: [
      {
        url: 'https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf',
        format: 'pdf',
        places: [{ key: 'client_signature', type: 'signature', recipient_key: 'client' }],
        fixed_positions: [{ place_key: 'client_signature', page: 1, top: 172, left: 210 }],
      },
    ],
    recipients: [
      {
        key: 'client',
        type: 'signer',
        name,
        email,
        delivery_type: 'none',
        ceremony: {
          authentication: [{ type: 'custom', provider: 'Acme Corp Portal', data: { user_id: userId } }],
          embeddable_in: [appOrigin],
        },
      },
    ],
  };
}
```

The envelope starts in `processing`, and the ceremony opens only once it is `in_progress`. `createSigningSession()` reads the envelope once a second until then and returns the ceremony URL from that read. Every read returns a [new URL for the same ceremony](https://signatureapi.com/docs/api/resources/ceremonies/ceremony-url#url-validity).

```javascript signatureapi.mjs
export async function createSigningSession(config, { name, email, userId }) {
  let envelope = await api(config, 'POST', '/v1/envelopes', buildContract({ name, email, userId, appOrigin: config.appOrigin }));
  for (let attempt = 0; envelope.status === 'processing' && attempt < 30; attempt += 1) {
    await new Promise((resolve) => setTimeout(resolve, 1000));
    envelope = await api(config, 'GET', `/v1/envelopes/${envelope.id}`);
  }
  if (envelope.status !== 'in_progress') throw new Error(`Envelope is ${envelope.status}, not ready for signing`);
  return { envelopeId: envelope.id, ceremonyUrl: envelope.recipients[0].ceremony.url };
}
```

## 2. Embed the ceremony

The page adds `embedded=true` and `event_delivery=message` to the ceremony URL and loads it in an iframe. It accepts [ceremony events](https://signatureapi.com/docs/embedded/ceremony-events) only from `https://sign.signatureapi.com` and from its own iframe.

```javascript public/index.html
const CEREMONY_ORIGIN = 'https://sign.signatureapi.com';
const iframe = document.getElementById('signatureapi-ceremony');
const status = document.getElementById('status');
let envelopeId = null;

document.getElementById('start').addEventListener('submit', async (event) => {
  event.preventDefault();
  const form = new FormData(event.target);
  const response = await fetch('/api/contracts', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name: form.get('name'), email: form.get('email') }),
  });
  const body = await response.json();
  if (!response.ok) { status.textContent = body.error; return; }
  envelopeId = body.envelopeId;
  // Both query parameters are required for an embedded ceremony.
  const src = new URL(body.ceremonyUrl);
  src.searchParams.set('embedded', 'true');
  src.searchParams.set('event_delivery', 'message');
  iframe.src = src.toString();
  iframe.classList.remove('hidden');
});

window.addEventListener('message', async (event) => {
  // Accept messages only from the ceremony iframe.
  if (event.origin !== CEREMONY_ORIGIN || event.source !== iframe.contentWindow) return;
  if (event.data.type === 'ceremony.completed') {
    iframe.classList.add('hidden');
    // The browser event is a UI signal. Confirm on your server before you act on it.
    const response = await fetch(`/api/contracts/${envelopeId}`);
    const body = await response.json();
    status.textContent = `Thanks! Envelope status: ${body.status}`;
    // The signed PDF is ready a few seconds after completion. Your server streams it (step 5).
    const download = document.getElementById('download');
    download.href = `/api/contracts/${envelopeId}/signed.pdf`;
    download.classList.remove('hidden');
  } else if (event.data.type === 'ceremony.canceled') {
    status.textContent = 'Signing canceled. You can start again any time.';
  } else if (event.data.type === 'ceremony.failed') {
    status.textContent = `Signing failed: ${event.data.error_message}`;
  }
});
```

A `ceremony.completed` message is a signal for your UI, not proof of signing: the page asks your server for the envelope status before it shows the result. To send the signer to the ceremony page instead of embedding it, open the URL without `embedded=true` and set a [redirect URL](https://signatureapi.com/docs/api/resources/ceremonies/redirect-url) for the way back.

## 3. Verify webhooks on the raw body

SignatureAPI signs every delivery with the [Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks) scheme. `verifyWebhook()` computes an HMAC-SHA256 over `webhook-id.webhook-timestamp.body` with your signing secret, compares it in constant time with each `v1` entry of `webhook-signature`, and rejects timestamps more than 5 minutes off. It runs on the exact bytes received: parsing and re-serializing the JSON changes them and breaks the signature.

```javascript signatureapi.mjs
export function verifyWebhook(secret, headers, rawBody, { now = Math.floor(Date.now() / 1000), toleranceSeconds = 300 } = {}) {
  const id = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  const signatures = headers['webhook-signature'];
  if (!id || !timestamp || !signatures) throw new Error('Missing webhook headers');
  if (!/^\d+$/.test(timestamp) || Math.abs(now - Number(timestamp)) > toleranceSeconds) {
    throw new Error('Webhook timestamp outside the tolerance window');
  }
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const expected = createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest();
  const valid = signatures.split(' ').some((entry) => {
    const [version, value] = entry.split(',');
    if (version !== 'v1' || !value) return false;
    const given = Buffer.from(value, 'base64');
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
  if (!valid) throw new Error('Invalid webhook signature');
  return JSON.parse(rawBody);
}
```

The handler reads the request body as a string without parsing it, verifies it, and skips any `webhook-id` it has already processed. Deliveries are retried for up to 48 hours and can repeat, so in production store the ids with a unique index. See [Webhooks](https://signatureapi.com/docs/api/webhooks).

```javascript server.mjs
if (req.method === 'POST' && url.pathname === '/webhooks/signatureapi') {
  const raw = await readBody(req);
  let event;
  try {
    event = verifyWebhook(config.webhookSecret, req.headers, raw);
  } catch (error) {
    return send(res, 400, { error: error.message });
  }
  const webhookId = req.headers['webhook-id'];
  if (seenWebhookIds.has(webhookId)) return send(res, 200, { duplicate: true });
  seenWebhookIds.add(webhookId);
  const envelopeId = event.data?.envelope_id;
  const record = contracts.get(envelopeId) ?? { status: 'unknown', events: [] };
  record.events.push(event.type);
  if (event.type === 'envelope.completed') record.status = 'completed';
  contracts.set(envelopeId, record);
  console.log(`webhook ${event.type} for envelope ${envelopeId}`);
  return send(res, 200, { received: true });
}
```

## 4. Confirm the status

`GET /api/contracts/{id}` reads the envelope with [`GET /v1/envelopes/{id}`](https://signatureapi.com/docs/api/resources/envelopes/get) and returns its status, together with the webhook events stored for it. The page calls it after the ceremony finishes.

## 5. Download the signed PDF

When the envelope completes, SignatureAPI generates the [deliverable](https://signatureapi.com/docs/api/resources/deliverables/object): the signed PDF with its audit log. `downloadSignedPdf()` reads the envelope, gets its deliverable, and downloads the file from the deliverable's `url`. That URL is pre-signed and expires after 1 hour, so the function asks for a fresh one on each download instead of storing it.

```javascript signatureapi.mjs
export async function downloadSignedPdf(config, envelopeId) {
  const envelope = await api(config, 'GET', `/v1/envelopes/${envelopeId}`);
  if (envelope.status !== 'completed' || !envelope.deliverable) {
    throw new NotReadyError(`Envelope is ${envelope.status}. The signed PDF exists once it is completed.`);
  }
  const deliverable = await api(config, 'GET', `/v1/deliverables/${envelope.deliverable.id}`);
  if (deliverable.status !== 'generated') {
    throw new NotReadyError(`Deliverable is ${deliverable.status}. Try again in a few seconds.`);
  }
  const response = await fetch(deliverable.url);
  if (!response.ok) throw new Error(`Download failed with ${response.status}`);
  return Buffer.from(await response.arrayBuffer());
}
```

Until the deliverable is generated, the route answers `409` and the page can try again a few seconds later. To store the PDF as soon as it exists, call the same function when your webhook handler receives `deliverable.generated`.

## Run it

```shell
export SIGNATUREAPI_KEY=YOUR_API_KEY            # your test key
export SIGNATUREAPI_WEBHOOK_SECRET=whsec_YOUR_SECRET
export APP_ORIGIN=http://localhost:3000
node server.mjs
```

Open <http://localhost:3000>, keep the sample name and email, and select **Start signing**. After you sign, the page shows `Thanks! Envelope status: completed` and a link to the signed PDF.

## Test it

```shell
npm test
```

The tests check the webhook verifier against a fixed test vector, then run the app against a local mock API: the envelope payload, the `422` path, webhook acceptance, tampering and duplicates, and the PDF download. With `SIGNATUREAPI_KEY` set to a test key, two more tests run against the API: one creates an embedded envelope and waits for `in_progress`, the other completes an envelope with an [automatic signer](https://signatureapi.com/docs/api/resources/recipients/automatic-signer) and downloads its signed PDF.

## Troubleshooting

- **The iframe is blank or refuses to load.** `embeddable_in` must match your page's origin exactly (scheme, host and port), and the URL needs `embedded=true`.
- **The ceremony asks the signer to try again later.** The envelope was still `processing`. Show the URL only after the envelope is `in_progress`, as step 1 does.
- **No `message` events arrive.** Add `event_delivery=message` to the URL and check that the origin filter uses `https://sign.signatureapi.com`.
- **Every webhook fails verification.** Each endpoint has its own signing secret, and a proxy or body parser may have changed the body before verification.
- **The download returns `409`.** The deliverable is still being generated. Wait for `deliverable.generated` or try again in a few seconds.

## Next steps

- [Embedding in a Web Application](https://signatureapi.com/docs/embedded/web-app): the full request flow and every ceremony option.
- [Webhooks](https://signatureapi.com/docs/api/webhooks): events, retries and source IPs.
- [Go-live checklist](https://signatureapi.com/docs/api/guides/go-live-checklist): what to check before you switch to a live key.
