---
title: "Embedded ceremony blank, blocked or silent"
description: "Fix an embedded signing ceremony that stays blank, is blocked in the iframe, says the link is invalid, or never sends its events to your web or mobile app."
canonical: "https://signatureapi.com/docs/troubleshooting/embedded"
source: "https://signatureapi.com/docs/troubleshooting/embedded.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T13:06:40Z"
---

# Embedded ceremony blank, blocked or silent

Fix an embedded signing ceremony that stays blank, is blocked in the iframe, says the link is invalid, or never sends its events to your web or mobile app.

_Last verified against API version 1.18.0._

An embedded ceremony shows the signing session inside your app, in an iframe on the web or a WebView on mobile. When it doesn't work, the symptom tells you where to look.

| What you see                                               | Go to                                                                                                                      |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| The iframe is blank or the browser refuses to load it      | [The iframe is blocked](https://signatureapi.com/docs/troubleshooting/embedded#the-iframe-is-blocked)                      |
| The ceremony asks the recipient to try again later         | [The envelope isn't ready](https://signatureapi.com/docs/troubleshooting/embedded#the-envelope-isnt-ready)                 |
| The ceremony says the link isn't valid                     | [The link is invalid or expired](https://signatureapi.com/docs/troubleshooting/embedded#the-link-is-invalid-or-expired)    |
| The ceremony works, but your app never hears that it ended | [Events don't reach your app](https://signatureapi.com/docs/troubleshooting/embedded#events-dont-reach-your-app)           |
| The ceremony doesn't load in a mobile app                  | [Mobile WebViews](https://signatureapi.com/docs/troubleshooting/embedded#mobile-webviews)                                  |
| An automated test sees "Confirm to continue"               | [Automated tests](https://signatureapi.com/docs/troubleshooting/embedded#automated-tests-see-a-confirm-to-continue-dialog) |

## The iframe is blocked

The browser console shows an error like "Refused to frame ... because an ancestor violates the following Content Security Policy directive". The ceremony only lets the origins you listed load it in an iframe. Check:

- **`embedded=true` is on the URL.** It lays out the ceremony for an iframe and sends the `frame-ancestors` policy built from your origins.
- **Your origin is in `embeddable_in`.** List the exact origin of the page that shows the iframe: scheme, host and port, such as `https://app.acme.example` or `http://localhost:3000`. A different port, `http` instead of `https`, or a `www.` prefix is a different origin.
- **Every environment is listed.** Staging, preview and production hosts each need their own entry, up to 10 origins. A wildcard such as `https://*.acme.example` covers subdomains.
- **The Embedder tool is listed while you test.** The [Embedder](https://signatureapi.github.io/embedder/) runs on its own origin, so add `https://signatureapi.github.io` while you use it.

`embeddable_in` is set when the ceremony is created. To change it, [create a new ceremony](https://signatureapi.com/docs/api/resources/ceremonies/create) for the recipient with the corrected list. See [CSP frame-ancestors error](https://signatureapi.com/docs/embedded/web-app#csp-frame-ancestors-error) for a step-by-step check.

### Your own page blocks it

Your site's Content Security Policy can block the ceremony too. If your page sets `frame-src` or `child-src`, allow `https://sign.signatureapi.com`. The ceremony also needs to reach a few other hosts; see [Browser requirements](https://signatureapi.com/docs/embedded/introduction#browser-requirements).

## The envelope isn't ready

The ceremony URL is in the `201 Created` response, but the ceremony opens only once the envelope is `in_progress`. Before that, it asks the recipient to try again later. Show it after the [`envelope.started`](https://signatureapi.com/docs/api/resources/events/envelope-events#envelopestarted) webhook, or after a read of the envelope returns `in_progress`.

With [sequential routing](https://signatureapi.com/docs/api/resources/envelopes/routing), a recipient's turn also has to come: show the ceremony to the recipient whose turn it is.

## The link is invalid or expired

A ceremony URL stops working when:

- **It expired.** A URL is valid for 30 days from when it's issued.
- **A newer ceremony replaced it.** Creating a ceremony for the same recipient revokes every earlier URL.
- **The ceremony ended.** The recipient completed or declined it, the envelope was canceled, or the recipient was replaced.
- **The URL was cut short.** Use the full URL, token included, exactly as the API returned it.

Ask your server for a fresh URL when you show the ceremony instead of storing one. See [Ceremony URL](https://signatureapi.com/docs/api/resources/ceremonies/ceremony-url#invalid-or-expired-links) for how to get a new one for each authentication method. An embedded ceremony also reports the reason in a `ceremony.failed` event; see [Error types](https://signatureapi.com/docs/embedded/ceremony-events#error-types).

## Events don't reach your app

### On the web

- **Add `event_delivery=message` to the URL.** Without it, the ceremony doesn't post events to your page.
- **Check your origin filter.** Accept messages whose `event.origin` is exactly `https://sign.signatureapi.com` and whose `event.source` is the iframe's `contentWindow`. A filter set to your own origin, or to the API host, drops every ceremony message.
- **Add the listener before the iframe loads,** so the first events aren't missed.

See [Listening to events](https://signatureapi.com/docs/embedded/web-app#listening-to-events) for a complete listener.

### In a native WebView

With `event_delivery=redirect`, the ceremony navigates the WebView to a `signatureapi-message://` URL that carries the event. Intercept that navigation in your WebView's navigation handler and read the event from it. See [Ceremony events](https://signatureapi.com/docs/embedded/ceremony-events#event-delivery).

## Mobile WebViews

- **Turn on JavaScript.** The ceremony is a JavaScript app. Android's `WebView` has JavaScript off by default; set `javaScriptEnabled = true`.
- **Load the ceremony as the page.** In a native app, load the ceremony URL as the WebView's own page. You then don't need `embeddable_in` or a host page.
- **Allow the ceremony hosts.** If your app restricts network access, allow the hosts in [Browser requirements](https://signatureapi.com/docs/embedded/introduction#browser-requirements).

The ceremony uses no cookies or browser storage, so storage and cookie settings don't matter. See the [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) guides.

## Automated tests see a "Confirm to continue" dialog

The ceremony arms **Finish** only after input a person produces: a touch, a scroll-wheel turn, a key press or a pointer moving across several positions. Until then, **Finish** opens a "Confirm to continue" dialog. Clicks dispatched from JavaScript don't count, so a test that only dispatches clicks sees the dialog. Add a real gesture first, such as a swipe or mouse movement. See [Automated testing](https://signatureapi.com/docs/embedded/introduction#automated-testing).

## Related

- [Embedded signing](https://signatureapi.com/docs/embedded/introduction): how it works.
- [Embed in a web app](https://signatureapi.com/docs/embedded/web-app): the iframe guide.
- [Ceremony customization](https://signatureapi.com/docs/embedded/customization): every URL parameter.
