Skip to content

Troubleshooting

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.

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 seeGo to
The iframe is blank or the browser refuses to load itThe iframe is blocked
The ceremony asks the recipient to try again laterThe envelope isn’t ready
The ceremony says the link isn’t validThe link is invalid or expired
The ceremony works, but your app never hears that it endedEvents don’t reach your app
The ceremony doesn’t load in a mobile appMobile WebViews
An automated test sees “Confirm to continue”Automated tests

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 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 for the recipient with the corrected list. See 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.

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 webhook, or after a read of the envelope returns in_progress.

With sequential routing, a recipient’s turn also has to come: show the ceremony to the recipient whose turn it is.

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 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.

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 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.

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.

The ceremony uses no cookies or browser storage, so storage and cookie settings don’t matter. See the iOS, Android, React Native and 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.