> ## Documentation Index
> Fetch the complete documentation index at: https://signatureapi-daf4ee54.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](#javascript-messages), ideal for web apps, and [redirects](#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:

```json theme={null}
{
	type: "ceremony.completed"
}
```

An example for a `ceremony.failed` event:

```json theme={null}
{
	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:

<div className="break-all font-mono text-sm border p-3 rounded"><span>signatureapi-message://</span>ceremony.completed</div>

The URL for a `ceremony.failed` event:

<div className="break-all font-mono text-sm border p-3 rounded"><span>signatureapi-message://</span>ceremony.failed/?error\_type=not\_available\&error\_message=The+ceremony+is+no+longer+available</div>