---
title: "Using JavaScript Event Notifiers"
slug: "using-javascript-event-notifiers"
updated: 2025-07-02T18:33:46Z
published: 2025-07-02T18:33:46Z
canonical: "docs.onespan.com/using-javascript-event-notifiers"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onespan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Using JavaScript Event Notifiers

To download the full code sample see our [Code Share](https://community.onespan.com/documentation/onespan-sign/codeshare/esignlive-event-notifier/) site.

When the Signer Experience is embedded in an iFrame, the Event Notifier sends notifications to your parent window when specific actions are triggered. Using these notifications you can interrupt the typical OneSpan Sign workflow using your own customized logic, and then resume normal activities after. This is useful if you want to something to happen after certain steps of the Signer Experience have been accomplished, such as redirecting a signer to a different web page once they have completed signing.

## Listening for OneSpan Sign events

To create an Event Notifier your application must be listening for OneSpan Sign message events. To set this up, use this command, using plain JavaScript:

```javascript
window.addEventListener('message', receiveMessage, false);
```

For more information on allowing cross-origin communication between your parent window and an iFrame, click [here](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage).

## Receving Messages

Next, define the receiveMessage function as follows:

```javascript
function receiveMessage(event) {
      var origin = event.origin || event.originalEvent.origin;
      var data = event.data;
      console.log(data, origin);
 
      switch (data) {
            case 'ESL:MESSAGE:REGISTER':
                  event.source.postMessage('ESL:MESSAGE:ACTIVATE_EVENTS', origin);
                  break;
            default:
                  event.source.postMessage(data, origin)
                  break;
      }
}
```

> If you do not configure your system to listen to ESL:MESSAGE:REGISTER and then send back ESL:MESSAGE:ACTIVATE_EVENTS, you will not be able to receive any further events. You must include the following in your receiveMessage function.
> 
> ```javascript
>   case 'ESL:MESSAGE:REGISTER':
> 				event.source.postMessage('ESL:MESSAGE:ACTIVATE_EVENTS', origin);
> 				break;
> 				default:
> 				event.source.postMessage(data, origin)
> 			break;
> ```

This is the minimal code needed to setup an Event Notifier, where the first switch case explicitly tells OneSpan Sign that you want to register for event listening.

## Results

A common use of an Event Notifier can be to redirect a signer to a different page once they have completed signing. Here is an example of how that would be done:

```javascript
case 'ESL:MESSAGE:SUCCESS:SIGNER_COMPLETE ':
	event.source.postMessage(data, origin);
	window.location.href = "https://www.example.com"; //redirect page
	break;
```

## Interrupting OneSpan Sign Activity

Using an Event Notifier, some events can be temporarily stopped. Here is some sample code that shows you how to do that:

```javascript
switch (data) {
   ...
   case 'ESL:MESSAGE:STARTED:DOCUMENT_NAVIGATION':
     // Do some customized tasks, then notify OneSpan Sign of the same event.
     setTimeout(function(){
       event.source.postMessage(data, origin);
     }, 5000);
     break;
   ...
}
```

For those events that can be interrupted, OneSpan Sign will not resume its normal activity until your parent container posts back the same message defined by the line event.source.postMessage(data, origin).

For more information on which events can be interrupted, see [Notification Event Types](/v1/docs/using-javascript-event-notifiers#notification-event-types).

## Notification Event Types

The following table describes the types of notification events your Event Notifier can listen for.

| Event Name | Description | Can Event Be Temporarily Stopped? |
| --- | --- | --- |
| ESL:MESSAGE:STARTED:DOCUMENT_ACCEPT | A signer has started to accept a consent or disclosure. | No |
| ESL:MESSAGE:SUCCESS:DOCUMENT_ACCEPT | A signer has successfully accepted a consent or disclosure. | Yes |
| ESL:MESSAGE:ERROR:DOCUMENT_ACCEPT | A signer has failed in their attempt to accept a consent or disclosure. | No |
| ESL:MESSAGE:STARTED:PACKAGE_OPT_OUT | A signer has started to opt out of a transaction. | No |
| ESL:MESSAGE:SUCCESS:PACKAGE_OPT_OUT | A signer has successfully opted out of a transaction. | Yes |
| ESL:MESSAGE:ERROR:PACKAGE_OPT_OUT | A signer has failed in their attempt to opt out of a transaction. | No |
| ESL:MESSAGE:STARTED:PACKAGE_DECLINE | A signer has started to decline a transaction. | No |
| ESL:MESSAGE:SUCCESS:PACKAGE_DECLINE | A signer has successfully declined a transaction. | Yes |
| ESL:MESSAGE:ERROR:PACKAGE_DECLINE | A signer has failed in their attempt to decline a transaction. | No |
| ESL:MESSAGE:SUCCESS:DOCUMENT_VIEW:<document Id> | A signer has viewed a document. | No |
| ESL:MESSAGE:STARTED:DOCUMENT_CONFIRM | A signer has started to confirm a document. | No |
| ESL:MESSAGE:SUCCESS:DOCUMENT_CONFIRM | A signer has successfully confirmed a document. | Yes |
| ESL:MESSAGE:ERROR:DOCUMENT_CONFIRM | A signer has failed in their attempt to confirm a document. | No |
| ESL:MESSAGE:STARTED:SIGNER_COMPLETE | A signer has started to complete a transaction. | Yes |
| ESL:MESSAGE:SUCCESS:SIGNER_COMPLETE | A signer has successfully completed a transaction. | No |
| ESL:MESSAGE:STARTED:SIGNER_COMPLETE_REVIEWED | A signer has started reviewing documents. | Yes |
| ESL:MESSAGE:SUCCESS:SIGNER_COMPLETE_REVIEWED | A signer has completed reviewing documents. | No |
| ESL:MESSAGE:STARTED:DOCUMENT_NAVIGATION | The user has started navigating to another document. | Yes |
| ESL:MESSAGE:SUCCESS:DOCUMENT_NAVIGATION | The user has successfully navigated to another document. | No |

Here is the expected order of events for a typical transaction with one external signer, a default Consent Document, and one document to be signed:

ESL:MESSAGE:REGISTER

ESL:MESSAGE:SUCCESS:DOCUMENT_NAVIGATION

ESL:MESSAGE:SUCCESS:DOCUMENT_VIEW

ESL:MESSAGE:STARTED:ACCEPT

ESL:MESSAGE:SUCCESS:ACCEPT

ESL:MESSAGE:STARTED:DOCUMENT_NAVIGATION

ESL:MESSAGE:SUCCESS:DOCUMENT_NAVIGATION

ESL:MESSAGE:SUCCESS:DOCUMENT_VIEW

ESL:MESSAGE:STARTED:DOCUMENT_CONFIRM

ESL:MESSAGE:SUCCESS:DOCUMENT_CONFIRM

ESL:MESSAGE:STARTED:SIGNER_COMPLETE

ESL:MESSAGE:SUCCESS:SIGNER_COMPLETE

ESL:MESSAGE:STARTED:SIGNER_COMPLETE_REVIEWED

ESL:MESSAGE:SUCCESS:SIGNER_COMPLETE_REVIEWED