---
title: "Embedding in a Web Application"
description: "Embed the signing ceremony in your web app with an iframe. Create the envelope on your server, allow your origin, show the ceremony and handle its events."
canonical: "https://signatureapi.com/docs/embedded/web-app"
source: "https://signatureapi.com/docs/embedded/web-app.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T12:39:46Z"
---

# Embedding in a Web Application

Embed the signing ceremony in your web app with an iframe. Create the envelope on your server, allow your origin, show the ceremony and handle its events.

_Last verified against API version 1.18.0._

Your web app shows the signing ceremony in an `<iframe>`, so the recipient signs without leaving your page. Your server creates the envelope with your API key and returns the ceremony URL; your page shows that URL and listens for the event that tells it how the ceremony ended.

**Embedded signing, from envelope to confirmed signature**

Participants: Your page, Your server, SignatureAPI, Ceremony iframe.

1. **Your page** to **Your server**: The signed-in user asks to sign
   Your server already knows who the user is. The browser never holds your API key.
2. **Your server** to **SignatureAPI**: Create envelope `POST /v1/envelopes`
   Give the recipient `custom` authentication so SignatureAPI returns the ceremony URL instead of emailing it, and list your page's origin in `ceremony.embeddable_in`.

   ```http
   POST /v1/envelopes HTTP/1.1
   Host: api.signatureapi.com
   X-API-Key: YOUR_API_KEY
   Content-Type: application/json
   
   {
     "title": "Service Agreement",
     "documents": [
       {
         "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf",
         "format": "pdf",
         "places": [
           { "key": "signer_signs_here", "type": "signature", "recipient_key": "client" }
         ]
       }
     ],
     "recipients": [
       {
         "type": "signer",
         "key": "client",
         "name": "Jane Doe",
         "email": "jane.doe@example.com",
         "ceremony": {
           "authentication": [
             { "type": "custom", "provider": "Acme Portal", "data": { "user_id": "usr_12345" } }
           ],
           "embeddable_in": ["https://app.acme.example"]
         }
       }
     ]
   }
   ```
3. **SignatureAPI** to **Your server**: `201 Created` with `recipients[].ceremony.url`
   The envelope starts in `processing`. The URL is already in the response, but the ceremony opens only once the envelope is `in_progress`.
4. **SignatureAPI** to **Your server**: Webhook `envelope.started`
   The envelope is now `in_progress`. Instead of a webhook, you can read the envelope with `GET /v1/envelopes/{id}` until its status is `in_progress`.
5. **Your server** to **Your page**: Return the ceremony URL
   The URL works like a password for this recipient: send it only to the signed-in user, and don't log it.
6. **Your page** to **Ceremony iframe**: Load the URL in an iframe
   Append `embedded=true` and `event_delivery=message` to the URL.
7. **Ceremony iframe**: The recipient reviews and signs
8. **Ceremony iframe** to **Your page**: Message `ceremony.completed`
   Accept it only when `event.origin` is `https://sign.signatureapi.com` and `event.source` is the iframe. Use it to update your page.
9. **SignatureAPI** to **Your server**: Webhook `recipient.completed`
   The message comes from the browser and the webhook from SignatureAPI, so the two can arrive in either order. Treat the webhook, or a read of the envelope, as the record that the recipient signed.

**Video: Signing in an iframe**

The web integration demo creates a test envelope, shows the ceremony in an iframe, receives ceremony.completed and shows Document signed.

[Watch the video](https://signatureapi.com/videos/web-embedded-signing.mp4)
[Captions (WebVTT)](https://signatureapi.com/videos/web-embedded-signing.vtt)

Using a framework? The same steps, with components and server code, are in the guides for [React](https://signatureapi.com/docs/embedded/frameworks/react), [Next.js](https://signatureapi.com/docs/embedded/frameworks/nextjs), [Vue and Nuxt](https://signatureapi.com/docs/embedded/frameworks/vue-nuxt), [Angular](https://signatureapi.com/docs/embedded/frameworks/angular) and [Svelte](https://signatureapi.com/docs/embedded/frameworks/svelte).

## Create the envelope on your server

Create the envelope on your server. Two settings on the recipient's `ceremony` make it embeddable:

- `authentication` starts with `custom`: your app has already signed the user in, so SignatureAPI returns the ceremony URL instead of emailing it. Put references to your own login session in `data`; they appear in the audit log. See [Custom authentication](https://signatureapi.com/docs/api/resources/ceremonies/authentication/custom).
- `embeddable_in` lists the origins allowed to show the ceremony in an iframe. Without it, the browser refuses to load the iframe.

```http
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "title": "Service Agreement",
  "documents": [
    {
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf",
      "format": "pdf",
      "places": [
        {
          "key": "signer_signs_here",
          "type": "signature",
          "recipient_key": "client"
        }
      ]
    }
  ],
  "recipients": [
    {
      "type": "signer",
      "key": "client",
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "ceremony": {
        "authentication": [
          {
            "type": "custom",
            "provider": "Acme Portal",
            "data": {
              "user_id": "usr_12345"
            }
          }
        ],
        "embeddable_in": [
          "https://app.acme.example"
        ]
      }
    }
  ]
}
```

Write each `embeddable_in` entry as an origin: the scheme, the host and the port if it isn't the default, such as `https://app.acme.example` or `http://localhost:3000` for local development. A path after the host is ignored. A wildcard covers subdomains, such as `https://*.acme.example`. You can list up to 10 origins.

SignatureAPI keeps `embeddable_in` only when the ceremony's first authentication method is `custom` or `email_code`. With `email_link` first, the recipient gets the link by email and the ceremony can't be embedded.

The `201 Created` response already includes the ceremony URL in `recipients[].ceremony.url`. The response below is trimmed to the recipient:

```json 201 Created
{
  "id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
  "title": "Service Agreement",
  "status": "processing",
  "recipients": [
    {
      "id": "re_49r1R2jpPDz8hSpP75ZkPp",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "type": "signer",
      "key": "client",
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "status": "pending",
      "ceremony": {
        "authentication": [
          {
            "type": "custom",
            "provider": "Acme Portal",
            "data": {
              "user_id": "usr_12345"
            }
          }
        ],
        "embeddable_in": [
          "https://app.acme.example"
        ],
        "redirect_url": null,
        "redirect_delay": 3,
        "url_variant": "standard",
        "url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR..."
      }
    }
  ]
}
```

The envelope starts in `processing`. The ceremony opens once the envelope is `in_progress`; if your page shows it earlier, the ceremony asks the recipient to try again later. Return the URL to your page after the [`envelope.started`](https://signatureapi.com/docs/api/resources/events/envelope-events#envelopestarted) webhook, or after reading the envelope with [`GET /v1/envelopes/{id}`](https://signatureapi.com/docs/api/resources/envelopes/get) and seeing `in_progress`. Every read returns a [new URL for the same ceremony](https://signatureapi.com/docs/api/resources/ceremonies/ceremony-url#url-validity); any of them works.

> **Warning:** Never call the API from the browser. Your API key would be exposed to anyone using your app, giving them access to all your data in SignatureAPI. Make API calls from your server and pass only the ceremony URL to the page.

The ceremony URL lets whoever holds it sign as the recipient. Send it only to the signed-in user it belongs to, and don't log it.

## The ceremony URL

Add two query parameters to the ceremony URL:

- `embedded=true` lays out the ceremony for an iframe and sends the `frame-ancestors` directive of the CSP built from `embeddable_in`.
- `event_delivery=message` sends [ceremony events](https://signatureapi.com/docs/embedded/ceremony-events), such as completion, to your page as [JavaScript messages](https://signatureapi.com/docs/embedded/ceremony-events#event-delivery).

Example URL with both query parameters:

```text
https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MjI4OTE3NDYsImV4cCI6MTcyMzQ5NjU0NiwiY2VyZW1vbnlf&embedded=true&event_delivery=message
```

Add them with the `URL` API rather than string concatenation:

```javascript
const url = new URL(ceremonyUrl);
url.searchParams.set('embedded', 'true');
url.searchParams.set('event_delivery', 'message');
iframe.src = url.toString();
```

Other query parameters change the accent color and the Cancel button. See [Ceremony Customization](https://signatureapi.com/docs/embedded/customization).

## The \<iframe> tag

Embed the signing interface using an [iframe tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) with the Ceremony URL as the `src` attribute.

> **Note:** Ensure you use the URL with the `embedded=true` and `event_delivery=message` query parameters appended.

```html
<iframe
  id="signatureapi-ceremony"
  title="SignatureAPI Signing Ceremony"
  width="800"
  height="600"
  src="https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MjI4OTE3NDYsImV4cCI6MTcyMzQ5NjU0NiwiY2VyZW1vbnlf&embedded=true&event_delivery=message">
</iframe>
```

## Testing with Embedder

Before you build the page, preview your ceremony in an iframe with the **Embedder** tool.

![Embedder tool with a ceremony URL field, width and height fields, and the ceremony preview in an iframe below them](https://signatureapi.com/docs/embedded/embedder.webp)

To use the Embedder:

1. Go to the [Embedder Tool](https://signatureapi.github.io/embedder/).
2. Enter your [ceremony URL](https://signatureapi.com/docs/api/resources/ceremonies/ceremony-url). The Embedder adds `embedded=true` and `event_delivery=message` for you.
3. Optionally, adjust the width and height in pixels.
4. The Embedder shows your ceremony in an iframe of that size.

The Embedder runs on its own origin, so add `https://signatureapi.github.io` to the ceremony's `embeddable_in` while you test with it.

## Listening to events

The embedded ceremony sends JavaScript [MessageEvent](https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent)s for [events happening inside the ceremony](https://signatureapi.com/docs/embedded/ceremony-events#event-types).

Your app can listen to these events and take actions, such as closing the iframe when the ceremony is completed. The ceremony posts each message with a target origin of `*`. The payload carries no secrets, but your page must check who sent it. Accept a message only when `event.origin` is `https://sign.signatureapi.com` and `event.source` is the iframe's `contentWindow`.

```javascript
const iframe = document.getElementById('signatureapi-ceremony');
const CEREMONY_ORIGIN = 'https://sign.signatureapi.com';

// Function to handle the ceremony completed event
function handleCeremonyCompleted(event) {
    console.log("Ceremony completed successfully.");
    // Confirm the outcome on your server before acting on it
}

// Function to handle the ceremony canceled event
function handleCeremonyCanceled(event) {
    console.log("Ceremony was canceled by the user.");
}

// Function to handle the ceremony declined event
function handleCeremonyDeclined(event) {
    console.log("Ceremony was declined.");
}

// Function to handle the ceremony failed event
function handleCeremonyFailed(event) {
    const { error_type, error_message } = event.data;
    console.error(`Ceremony failed with error: ${error_type} - ${error_message}`);
}

// Function to handle incoming message events
function handleMessage(event) {
    // Ignore messages that do not come from the ceremony iframe
    if (event.origin !== CEREMONY_ORIGIN) return;
    if (event.source !== iframe.contentWindow) return;

    const { type } = event.data;

    switch (type) {
        case 'ceremony.completed':
            handleCeremonyCompleted(event);
            break;
        case 'ceremony.canceled':
            handleCeremonyCanceled(event);
            break;
        case 'ceremony.declined':
            handleCeremonyDeclined(event);
            break;
        case 'ceremony.failed':
            handleCeremonyFailed(event);
            break;
        default:
            console.warn(`Unknown event type: ${type}`);
    }
}

// Add event listener to window for message events
window.addEventListener('message', handleMessage, false);
```

> **Note:** A `ceremony.completed` event is a signal for your UI, not proof that the envelope is complete. [Confirm the outcome on your server](https://signatureapi.com/docs/embedded/ceremony-events#confirm-the-outcome-on-your-server) before you act on it.

## Troubleshooting

### CSP frame-ancestors error

If the browser refuses to load the iframe and you see an error like this in the console:

> Refused to frame ... because an ancestor violates the following Content Security Policy directive: "frame-ancestors none".

Check the following:

- **`embedded=true` query parameter is present.** Without it, the correct CSP headers are not set and the browser blocks the iframe.
- **`embeddable_in` is set correctly.** The array must include the exact origin where your app is hosted (for example, `https://app.acme.example`). Include the protocol (`https://`) and omit trailing slashes or paths.
- **Localhost testing.** Use `http://localhost:3000` (with your port number) in `embeddable_in` during development.
- **Multiple origins.** If your app runs on multiple domains, include all of them in the `embeddable_in` array.

To isolate the issue, create a test ceremony with `embeddable_in` set to `["*"]`, which allows any origin. If that ceremony loads, the origin list of the original one is wrong. Use [Create Ceremony](https://signatureapi.com/docs/api/resources/ceremonies/create) to give the recipient a new ceremony:

```http
POST /v1/recipients/re_49r1R2jpPDz8hSpP75ZkPp/ceremonies HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "authentication": [
    {
      "type": "custom",
      "provider": "Acme Portal",
      "data": {
        "user_id": "usr_12345"
      }
    }
  ],
  "embeddable_in": [
    "*"
  ]
}
```

> **Warning:** Do not use the `*` wildcard in production. It allows any website to embed your signing ceremony, which is a security risk.

### The ceremony says to try again later

The envelope is still `processing`. Show the ceremony after the `envelope.started` webhook, or once a read of the envelope returns `in_progress`.

## Keep learning

- [Ceremony Events](https://signatureapi.com/docs/embedded/ceremony-events): every event, its payload and when it arrives.
- [Ceremony Customization](https://signatureapi.com/docs/embedded/customization): accent color, Cancel button and result page delay.
- [Authentication methods](https://signatureapi.com/docs/api/resources/ceremonies/authentication/overview): how recipients prove who they are before signing.
- [iOS](https://signatureapi.com/docs/embedded/ios), [Android](https://signatureapi.com/docs/embedded/android), [React Native](https://signatureapi.com/docs/embedded/react-native) and [Flutter](https://signatureapi.com/docs/embedded/flutter): embed the ceremony in a mobile app.
