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 see | Go to |
|---|---|
| The iframe is blank or the browser refuses to load it | The iframe is blocked |
| The ceremony asks the recipient to try again later | The envelope isn’t ready |
| The ceremony says the link isn’t valid | The link is invalid or expired |
| The ceremony works, but your app never hears that it ended | Events don’t reach your app |
| The ceremony doesn’t load in a mobile app | Mobile 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=trueis on the URL. It lays out the ceremony for an iframe and sends theframe-ancestorspolicy 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 ashttps://app.acme.exampleorhttp://localhost:3000. A different port,httpinstead ofhttps, or awww.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.examplecovers subdomains. - The Embedder tool is listed while you test. The Embedder runs on its own origin, so add
https://signatureapi.github.iowhile 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.
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 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=messageto the URL. Without it, the ceremony doesn’t post events to your page. - Check your origin filter. Accept messages whose
event.originis exactlyhttps://sign.signatureapi.comand whoseevent.sourceis the iframe’scontentWindow. 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
WebViewhas JavaScript off by default; setjavaScriptEnabled = 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_inor 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.
Related
- Embedded signing: how it works.
- Embed in a web app: the iframe guide.
- Ceremony customization: every URL parameter.