Ceremony Events
When an embedded ceremony reaches a terminal state, such as when the recipient signs the documents, it triggers an event.
Your application should listen for these events and respond accordingly. For instance, you can close the iframe in a web app once the ceremony is complete.
We offer two event delivery methods: Standard JavaScript messages, ideal for web apps, and redirects, commonly used in mobile and native apps.
Event types
There are 3 types of ceremony events:
| Event | Description |
|---|---|
ceremony.completed | The recipient has completed (for example signed) the envelope |
ceremony.canceled | The recipient has canceled the ceremony, for example by clicking the X icon |
ceremony.failed | An error happened and the ceremony can’t be completed |
For ceremony.failed events, the event includes an error_type and an error_message that explains the error:
| Error Type | Error Message |
|---|---|
already_completed | The ceremony has already been completed. |
not_available | The ceremony is no longer available. |
unauthorized | The ceremony URL is invalid |
Event delivery
We offer two ways to deliver the event from inside the ceremony to your application:
| Delivery type | When to use |
|---|---|
| Javascript messages | Use this when embedding in web apps using <iframe> |
| Deeplink redirects | Use this when embedding in desktop or mobile apps using WebView or similar. |
Javascript messages
The events are delivered to the parent application as a MessageEvent with a payload. For example the payload for a ceremony.completed event is:
{
type: "ceremony.completed"
}
An example for a ceremony.failed event:
{
type: "ceremony.failed",
error_type: "not_available",
error_message: "The ceremony is no longer available."
}
Redirects
The events are emitted as 301 redirects to URLs with a special scheme signatureapi-message://. Your app should detect and intercept the visits to URLs with this structure.
The event type is included as the host part of the URL, and any other data is included as query parameters, URL-encoded. For example the URL for a ceremony.completed event is:
The URL for a ceremony.failed event:
Was this page helpful?