Ceremony Events

Handle signing completion events via JavaScript messages or redirects in embedded ceremonies

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:

signatureapi-message://ceremony.completed

The URL for a ceremony.failed event:

signatureapi-message://ceremony.failed/?error_type=not_available&error_message=The+ceremony+is+no+longer+available