To download the full code sample see our Code Share site.

Callback Event Notifications enable you to be automatically notified of events that pertain to a package (in the New User Experience, packages are called "transactions"). When a specific event occurs, the system will automatically send a message to a destination that you have chosen.

Location in the UI

First, you should locate this area in your UI. After you run your code, you will be able to check here to make sure it ran successfully. To find the callback area from the UI, log into OneSpan Sign and click Admin > Event Notification.

Available Notifications

Before moving on to the code, it would be good to know all of the notifications available. As you can see in the image above, there are several. The following table lists them as they need to be represented, in your code:

In the following table:

  • The maximum size for all sessionUser fields is 255 characters.
  • The maximum size for all packageId fields is 255 characters.
  • The sessionUser field depends on whether or not the event was generated by a sender, or by a signer. Sender triggered events will have the sender ID. Signer triggered events will have the signer ID.
Event Meaning JSON Payload
COBROWSE_REQUEST A co-browse request occurs when a regular signer requests a co-browsing session with the transaction sender, typically to receive help in completing the transaction. This request notifies the sender in the format of a callback notification.

{ "name": "COBROWSE_REQUEST",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z"

"phone":"......",

"comment":"......",

"selectedSupportBusinessHours":["Morning - 9AM to 12PM ((GMT 0:00) GMT)"]}

DOCUMENT_SIGNED A document was signed, or Consent and/or Disclosure Agreements were accepted.

{ "name": "DOCUMENT_SIGNED",

"sessionUser": "...",

"packageId": "......",

"documentId": "......", (max 256 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

DOCUMENT_VIEWED A document was viewed.

{ "name": "DOCUMENT_VIEWED",

"sessionUser": "...",

"packageId": "......",

"documentId": "......", (max 256 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

EMAIL_BOUNCE

An email has bounced. The bounce types are the following:

  • "BOUNCE" (a hard bounce)
  • "COMPLAINT" (a soft bounce)
  • "OOTO" (out-of-the-office)
  • "UNKNOWN"

For more information, see our list of templates.

{ "name": "EMAIL_BOUNCE",

"sessionUser": "...",

"packageId": "......",

"message": "bounce type",

"createdDate": "2017-05-02T20:17:58.408Z" }

KBA_FAILURE There has been a KBA Authentication failure.

{ "name": "KBA_FAILURE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_ACTIVATE A package was moved from the status DRAFT or DELETED to the status SENT. By default, a package is created in the DRAFT state, and is moved to the SENT state when it's ready to be processed by signers.

{ "name": "PACKAGE_ACTIVATE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_ARCHIVE A callback notification indicates that a package has been archived.

{ "name": "PACKAGE_ARCHIVE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_ATTACHMENT A callback notification indicates that a signer has uploaded an attachment.

{ "name": "PACKAGE_ATTACHMENT",

"sessionUser": "...",

"packageId": "......",

"message": "attachment name", (max 255 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_COMPLETE

A package has completed the signing process.

If there are multiple signers then the "sessionUser": "...", will be the signer ID of the last signer to sign.

{ "name": 'PACKAGE_COMPLETE',

"sessionUser": '...',

"packageId": '......',

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_CREATE A package has been created. Thus the Originating System can record OneSpan Sign.com's package ID, together with the Originating System's transaction ID.

{ "name": "PACKAGE_CREATE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_DEACTIVATE A package's status has changed from SENT to DRAFT.

{ "name": "PACKAGE_DEACTIVATE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_DECLINE A recipient has declined to sign a package, and has specified a reason for doing so, The Originating System can use that reason to determine the next step for the package.

{ "name": "PACKAGE_DECLINE",

"sessionUser": "...",

"packageId": "......",

"message": "decline reason", (max 4000 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_DELETE A package has been deleted from the OneSpan Sign.com system.

{ "name": "PACKAGE_DELETE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_EXPIRE A package has exceeded its expiration date.

{ "name": "PACKAGE_EXPIRE",

"sessionUser": "...",

"packageId": "...",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_READY_FOR_COMPLETE A package has been marked as DO_NOT_AUTOCOMPLETE. An action by the sender will be required to complete the package.

{ "name": "PACKAGE_READY_FOR_COMPLETE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_RESTORE A package was trashed, but is being moved back to the state it was in before it was trashed.

{ "name": "PACKAGE_RESTORE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_TRASH A package was moved to the trash folder in OneSpan Sign's Inbox (status = TRASH).

{ "name": "PACKAGE_TRASH",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

RECORDINGS_READY After all signers have finished signing a Virtual Room transaction, the recorded session is processed. Once the recordings are ready to download, this notification is sent.

{ "name":"RECORDINGS_READY",

"sessionUser":"...",

"packageId": "......",

"createdDate":"2022-06-03T14:46:36.808Z"}

ROLE_REASSIGN A signer has delegated their signature to another signer. When this happens, OneSpan Sign creates a new role with a new signer. It is a good idea at that point to obtain the signer id of this new role. It is the signer id, not the role id, that will be part of future events such as SIGNER_COMPLETE. Knowing the signer id, which is passed in the sessionUser element of this event (and others) will make it easier to track the status of signers.

{ "name": "ROLE_REASSIGN",

"sessionUser": "...",

"packageId": "......",

"newRoleId": "......", (max 255 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

SIGNER_COMPLETE A signer has completed signing all documents.

{ "name": "SIGNER_COMPLETE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

SIGNER_LOCKED A callback notification indicates that a signer has been locked out due to repeated SMS/Q&A authentication failures.

{ "name": "SIGNER_LOCKED",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

TEMPLATE_CREATE A callback notification indicates that a template has been created.

{ "name": "TEMPLATE_CREATE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

Receiving Event Notifications

Once you've registered to be notified about one or more event types, you need only listen for the associated notifications. When a relevant event is triggered, OneSpan Sign will send an HTTP POST to your registered URL. That message contains a payload in JSON format, describing the event that triggered the notification.

The callback key you registered is passed through the Authorization header as "Basic {callbackKey}". You've use this to make sure you’re receiving notifications that contain the shared secret, so you know you’re not getting spoof calls and can react accordingly.

Below are few callback payload examples:

Package was Created
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"PACKAGE_CREATE","sessionUser":"18EZDL44xgsX","packageId":"wVdZEaPD2igwUnFGJBjDD0dpO7k=","message":null,"documentId":null,"createdDate":"2018-06-30T20:04:55.384Z"}
Package was Sent
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"PACKAGE_ACTIVATE","sessionUser":"18EZDL44xgsX","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":null,"createdDate":"2018-06-30T20:09:50.425Z"}
Signer 1 accepted consent document
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"DOCUMENT_SIGNED","sessionUser":"44aafb7c-97b9-40e1-bb59-eb76c7d2a484","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":"default-consent","createdDate":"2018-06-30T20:10:51.002Z"}
Signer 1 completed a document
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"DOCUMENT_SIGNED","sessionUser":"44aafb7c-97b9-40e1-bb59-eb76c7d2a484","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":"7caf46cdd75f7a411bf8c22793b84fa79d8d180becc40691","createdDate":"2018-06-30T20:12:12.256Z"}
Signer 1 completed signing package
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"SIGNER_COMPLETE","sessionUser":"44aafb7c-97b9-40e1-bb59-eb76c7d2a484","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":null,"createdDate":"2018-06-30T20:12:12.272Z"}
Package was Complete
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"PACKAGE_COMPLETE","sessionUser":"e00696ec-d6f5-4feb-89c5-a5ce002a6c66","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":null,"createdDate":"2018-06-30T20:15:01.038Z"}

Setting Up Callback Notifications

The following code samples can be used to set the callback URL, callback key, and subscribe you to three different event notifications.

  1. Create your EslClient with your API_KEY and API_URL (remember to use apps instead of your sandbox for production environments). Be sure to change the API_KEY, API_URL, URL, and KEY to your own values.
    final String API_KEY = "YOUR_API_KEY";
final String API_URL = "https://sandbox.esignlive.com/api";
final String URL = "http://my.url.com";
final String KEY = "myCallbackKey";
EslClient eslClient = new EslClient( API_KEY, API_URL );
  2. Call on your EventNotificationService to register for PACKAGE_CREATE, PACKAGE_DECLINE, and PACKAGE_COMPLETE notifications. You can also add more notification subscriptions from the table of options, above.
    3. eslClient.getEventNotificationService().register(newEventNotificationConfig(URL)
                .withKey(KEY)
                .forEvent(NotificationEvent.PACKAGE_CREATE)
                .forEvent(NotificationEvent.PACKAGE_DECLINE)
                .forEvent(NotificationEvent.PACKAGE_COMPLETE));

The Result

After running your code, click Admin > Event Notification. You will see that your selected Event Notifications have been toggled on.

To download the full code sample see our Code Share site.

Callback Event Notifications enable you to be automatically notified of events that pertain to a package (in the New User Experience, packages are called "transactions"). When a specific event occurs, the system will automatically send a message to a destination that you have chosen.

Location in the UI

First, you should locate this area in your UI. After you run your code, you will be able to check here to make sure it ran successfully. To find the callback area from the UI, log into OneSpan Sign and click Admin > Event Notification.

Available Notifications

Before moving on to the code, it would be good to know all of the notifications available. As you can see in the image above, there are several. The following table lists them as they need to be represented, in your code:

In the following table:

  • The maximum size for all sessionUser fields is 255 characters.
  • The maximum size for all packageId fields is 255 characters.
  • The sessionUser field depends on whether or not the event was generated by a sender, or by a signer. Sender triggered events will have the sender ID. Signer triggered events will have the signer ID.
Event Meaning JSON Payload
COBROWSE_REQUEST A co-browse request occurs when a regular signer requests a co-browsing session with the transaction sender, typically to receive help in completing the transaction. This request notifies the sender in the format of a callback notification.

{ "name": "COBROWSE_REQUEST",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z"

"phone":"......",

"comment":"......",

"selectedSupportBusinessHours":["Morning - 9AM to 12PM ((GMT 0:00) GMT)"]}

DOCUMENT_SIGNED A document was signed, or Consent and/or Disclosure Agreements were accepted.

{ "name": "DOCUMENT_SIGNED",

"sessionUser": "...",

"packageId": "......",

"documentId": "......", (max 256 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

DOCUMENT_VIEWED A document was viewed.

{ "name": "DOCUMENT_VIEWED",

"sessionUser": "...",

"packageId": "......",

"documentId": "......", (max 256 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

EMAIL_BOUNCE

An email has bounced. The bounce types are the following:

  • "BOUNCE" (a hard bounce)
  • "COMPLAINT" (a soft bounce)
  • "OOTO" (out-of-the-office)
  • "UNKNOWN"

For more information, see our list of templates.

{ "name": "EMAIL_BOUNCE",

"sessionUser": "...",

"packageId": "......",

"message": "bounce type",

"createdDate": "2017-05-02T20:17:58.408Z" }

KBA_FAILURE There has been a KBA Authentication failure.

{ "name": "KBA_FAILURE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_ACTIVATE A package was moved from the status DRAFT or DELETED to the status SENT. By default, a package is created in the DRAFT state, and is moved to the SENT state when it's ready to be processed by signers.

{ "name": "PACKAGE_ACTIVATE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_ARCHIVE A callback notification indicates that a package has been archived.

{ "name": "PACKAGE_ARCHIVE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_ATTACHMENT A callback notification indicates that a signer has uploaded an attachment.

{ "name": "PACKAGE_ATTACHMENT",

"sessionUser": "...",

"packageId": "......",

"message": "attachment name", (max 255 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_COMPLETE

A package has completed the signing process.

If there are multiple signers then the "sessionUser": "...", will be the signer ID of the last signer to sign.

{ "name": 'PACKAGE_COMPLETE',

"sessionUser": '...',

"packageId": '......',

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_CREATE A package has been created. Thus the Originating System can record OneSpan Sign.com's package ID, together with the Originating System's transaction ID.

{ "name": "PACKAGE_CREATE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_DEACTIVATE A package's status has changed from SENT to DRAFT.

{ "name": "PACKAGE_DEACTIVATE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_DECLINE A recipient has declined to sign a package, and has specified a reason for doing so, The Originating System can use that reason to determine the next step for the package.

{ "name": "PACKAGE_DECLINE",

"sessionUser": "...",

"packageId": "......",

"message": "decline reason", (max 4000 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_DELETE A package has been deleted from the OneSpan Sign.com system.

{ "name": "PACKAGE_DELETE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_EXPIRE A package has exceeded its expiration date.

{ "name": "PACKAGE_EXPIRE",

"sessionUser": "...",

"packageId": "...",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_READY_FOR_COMPLETE A package has been marked as DO_NOT_AUTOCOMPLETE. An action by the sender will be required to complete the package.

{ "name": "PACKAGE_READY_FOR_COMPLETE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_RESTORE A package was trashed, but is being moved back to the state it was in before it was trashed.

{ "name": "PACKAGE_RESTORE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_TRASH A package was moved to the trash folder in OneSpan Sign's Inbox (status = TRASH).

{ "name": "PACKAGE_TRASH",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

RECORDINGS_READY After all signers have finished signing a Virtual Room transaction, the recorded session is processed. Once the recordings are ready to download, this notification is sent.

{ "name":"RECORDINGS_READY",

"sessionUser":"...",

"packageId": "......",

"createdDate":"2022-06-03T14:46:36.808Z"}

ROLE_REASSIGN A signer has delegated their signature to another signer. When this happens, OneSpan Sign creates a new role with a new signer. It is a good idea at that point to obtain the signer id of this new role. It is the signer id, not the role id, that will be part of future events such as SIGNER_COMPLETE. Knowing the signer id, which is passed in the sessionUser element of this event (and others) will make it easier to track the status of signers.

{ "name": "ROLE_REASSIGN",

"sessionUser": "...",

"packageId": "......",

"newRoleId": "......", (max 255 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

SIGNER_COMPLETE A signer has completed signing all documents.

{ "name": "SIGNER_COMPLETE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

SIGNER_LOCKED A callback notification indicates that a signer has been locked out due to repeated SMS/Q&A authentication failures.

{ "name": "SIGNER_LOCKED",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

TEMPLATE_CREATE A callback notification indicates that a template has been created.

{ "name": "TEMPLATE_CREATE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

Receiving Event Notifications

Once you've registered to be notified about one or more event types, you need only listen for the associated notifications. When a relevant event is triggered, OneSpan Sign will send an HTTP POST to your registered URL. That message contains a payload in JSON format, describing the event that triggered the notification.

The callback key you registered is passed through the Authorization header as "Basic {callbackKey}". You've use this to make sure you’re receiving notifications that contain the shared secret, so you know you’re not getting spoof calls and can react accordingly.

Below are few callback payload examples:

Package was Created
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"PACKAGE_CREATE","sessionUser":"18EZDL44xgsX","packageId":"wVdZEaPD2igwUnFGJBjDD0dpO7k=","message":null,"documentId":null,"createdDate":"2018-06-30T20:04:55.384Z"}
Package was Sent
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"PACKAGE_ACTIVATE","sessionUser":"18EZDL44xgsX","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":null,"createdDate":"2018-06-30T20:09:50.425Z"}
Signer 1 accepted consent document
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"DOCUMENT_SIGNED","sessionUser":"44aafb7c-97b9-40e1-bb59-eb76c7d2a484","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":"default-consent","createdDate":"2018-06-30T20:10:51.002Z"}
Signer 1 completed a document
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"DOCUMENT_SIGNED","sessionUser":"44aafb7c-97b9-40e1-bb59-eb76c7d2a484","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":"7caf46cdd75f7a411bf8c22793b84fa79d8d180becc40691","createdDate":"2018-06-30T20:12:12.256Z"}
Signer 1 completed signing package
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"SIGNER_COMPLETE","sessionUser":"44aafb7c-97b9-40e1-bb59-eb76c7d2a484","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":null,"createdDate":"2018-06-30T20:12:12.272Z"}
Package was Complete
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"PACKAGE_COMPLETE","sessionUser":"e00696ec-d6f5-4feb-89c5-a5ce002a6c66","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":null,"createdDate":"2018-06-30T20:15:01.038Z"}

Setting Up Callback Notifications

The following code samples can be used to set the callback URL, callback key, and subscribe you to three different event notifications.

  1. Create your EslClient with your API_KEY and API_URL (remember to use apps instead of your sandbox for production environments). Be sure to change the API_KEY, API_URL, URL, and KEY to your own values.
    final String API_KEY = "YOUR_API_KEY";
final String API_URL = "https://sandbox.esignlive.com/api";
final String URL = "http://my.url.com";
final String KEY = "myCallbackKey";
EslClient eslClient = new EslClient( API_KEY, API_URL );
  2. Call on your EventNotificationService to register for PACKAGE_CREATE, PACKAGE_DECLINE, and PACKAGE_COMPLETE notifications. You can also add more notification subscriptions from the table of options, above.
    3. eslClient.getEventNotificationService().register(newEventNotificationConfig(URL)
                .withKey(KEY)
                .forEvent(NotificationEvent.PACKAGE_CREATE)
                .forEvent(NotificationEvent.PACKAGE_DECLINE)
                .forEvent(NotificationEvent.PACKAGE_COMPLETE));

The Result

After running your code, click Admin > Event Notification. You will see that your selected Event Notifications have been toggled on.

To download the full code sample see our Code Share site.

Callback Event Notifications enable you to be automatically notified of events that pertain to a package (in the New User Experience, packages are called "transactions"). When a specific event occurs, the system will automatically send a message to a destination that you have chosen.

Location in the UI

First, you should locate this area in your UI. After you run your code, you will be able to check here to make sure it ran successfully. To find the callback area from the UI, log into OneSpan Sign and click Admin > Event Notification.

Available Notifications

Before moving on to the code, it would be good to know all of the notifications available. As you can see in the image above, there are several. The following table lists them as they need to be represented, in your code:

In the following table:

  • The maximum size for all sessionUser fields is 255 characters.
  • The maximum size for all packageId fields is 255 characters.
  • The sessionUser field depends on whether or not the event was generated by a sender, or by a signer. Sender triggered events will have the sender ID. Signer triggered events will have the signer ID.
Event Meaning JSON Payload
COBROWSE_REQUEST A co-browse request occurs when a regular signer requests a co-browsing session with the transaction sender, typically to receive help in completing the transaction. This request notifies the sender in the format of a callback notification.

{ "name": "COBROWSE_REQUEST",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z"

"phone":"......",

"comment":"......",

"selectedSupportBusinessHours":["Morning - 9AM to 12PM ((GMT 0:00) GMT)"]}

DOCUMENT_SIGNED A document was signed, or Consent and/or Disclosure Agreements were accepted.

{ "name": "DOCUMENT_SIGNED",

"sessionUser": "...",

"packageId": "......",

"documentId": "......", (max 256 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

DOCUMENT_VIEWED A document was viewed.

{ "name": "DOCUMENT_VIEWED",

"sessionUser": "...",

"packageId": "......",

"documentId": "......", (max 256 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

EMAIL_BOUNCE

An email has bounced. The bounce types are the following:

  • "BOUNCE" (a hard bounce)
  • "COMPLAINT" (a soft bounce)
  • "OOTO" (out-of-the-office)
  • "UNKNOWN"

For more information, see our list of templates.

{ "name": "EMAIL_BOUNCE",

"sessionUser": "...",

"packageId": "......",

"message": "bounce type",

"createdDate": "2017-05-02T20:17:58.408Z" }

KBA_FAILURE There has been a KBA Authentication failure.

{ "name": "KBA_FAILURE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_ACTIVATE A package was moved from the status DRAFT or DELETED to the status SENT. By default, a package is created in the DRAFT state, and is moved to the SENT state when it's ready to be processed by signers.

{ "name": "PACKAGE_ACTIVATE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_ARCHIVE A callback notification indicates that a package has been archived.

{ "name": "PACKAGE_ARCHIVE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_ATTACHMENT A callback notification indicates that a signer has uploaded an attachment.

{ "name": "PACKAGE_ATTACHMENT",

"sessionUser": "...",

"packageId": "......",

"message": "attachment name", (max 255 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_COMPLETE

A package has completed the signing process.

If there are multiple signers then the "sessionUser": "...", will be the signer ID of the last signer to sign.

{ "name": 'PACKAGE_COMPLETE',

"sessionUser": '...',

"packageId": '......',

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_CREATE A package has been created. Thus the Originating System can record OneSpan Sign.com's package ID, together with the Originating System's transaction ID.

{ "name": "PACKAGE_CREATE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_DEACTIVATE A package's status has changed from SENT to DRAFT.

{ "name": "PACKAGE_DEACTIVATE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_DECLINE A recipient has declined to sign a package, and has specified a reason for doing so, The Originating System can use that reason to determine the next step for the package.

{ "name": "PACKAGE_DECLINE",

"sessionUser": "...",

"packageId": "......",

"message": "decline reason", (max 4000 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_DELETE A package has been deleted from the OneSpan Sign.com system.

{ "name": "PACKAGE_DELETE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_EXPIRE A package has exceeded its expiration date.

{ "name": "PACKAGE_EXPIRE",

"sessionUser": "...",

"packageId": "...",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_READY_FOR_COMPLETE A package has been marked as DO_NOT_AUTOCOMPLETE. An action by the sender will be required to complete the package.

{ "name": "PACKAGE_READY_FOR_COMPLETE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_RESTORE A package was trashed, but is being moved back to the state it was in before it was trashed.

{ "name": "PACKAGE_RESTORE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_TRASH A package was moved to the trash folder in OneSpan Sign's Inbox (status = TRASH).

{ "name": "PACKAGE_TRASH",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

RECORDINGS_READY After all signers have finished signing a Virtual Room transaction, the recorded session is processed. Once the recordings are ready to download, this notification is sent.

{ "name":"RECORDINGS_READY",

"sessionUser":"...",

"packageId": "......",

"createdDate":"2022-06-03T14:46:36.808Z"}

ROLE_REASSIGN A signer has delegated their signature to another signer. When this happens, OneSpan Sign creates a new role with a new signer. It is a good idea at that point to obtain the signer id of this new role. It is the signer id, not the role id, that will be part of future events such as SIGNER_COMPLETE. Knowing the signer id, which is passed in the sessionUser element of this event (and others) will make it easier to track the status of signers.

{ "name": "ROLE_REASSIGN",

"sessionUser": "...",

"packageId": "......",

"newRoleId": "......", (max 255 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

SIGNER_COMPLETE A signer has completed signing all documents.

{ "name": "SIGNER_COMPLETE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

SIGNER_LOCKED A callback notification indicates that a signer has been locked out due to repeated SMS/Q&A authentication failures.

{ "name": "SIGNER_LOCKED",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

TEMPLATE_CREATE A callback notification indicates that a template has been created.

{ "name": "TEMPLATE_CREATE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

Receiving Event Notifications

Once you've registered to be notified about one or more event types, you need only listen for the associated notifications. When a relevant event is triggered, OneSpan Sign will send an HTTP POST to your registered URL. That message contains a payload in JSON format, describing the event that triggered the notification.

The callback key you registered is passed through the Authorization header as "Basic {callbackKey}". You've use this to make sure you’re receiving notifications that contain the shared secret, so you know you’re not getting spoof calls and can react accordingly.

Below are few callback payload examples:

Package was Created
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"PACKAGE_CREATE","sessionUser":"18EZDL44xgsX","packageId":"wVdZEaPD2igwUnFGJBjDD0dpO7k=","message":null,"documentId":null,"createdDate":"2018-06-30T20:04:55.384Z"}
Package was Sent
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"PACKAGE_ACTIVATE","sessionUser":"18EZDL44xgsX","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":null,"createdDate":"2018-06-30T20:09:50.425Z"}
Signer 1 accepted consent document
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"DOCUMENT_SIGNED","sessionUser":"44aafb7c-97b9-40e1-bb59-eb76c7d2a484","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":"default-consent","createdDate":"2018-06-30T20:10:51.002Z"}
Signer 1 completed a document
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"DOCUMENT_SIGNED","sessionUser":"44aafb7c-97b9-40e1-bb59-eb76c7d2a484","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":"7caf46cdd75f7a411bf8c22793b84fa79d8d180becc40691","createdDate":"2018-06-30T20:12:12.256Z"}
Signer 1 completed signing package
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"SIGNER_COMPLETE","sessionUser":"44aafb7c-97b9-40e1-bb59-eb76c7d2a484","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":null,"createdDate":"2018-06-30T20:12:12.272Z"}
Package was Complete
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"PACKAGE_COMPLETE","sessionUser":"e00696ec-d6f5-4feb-89c5-a5ce002a6c66","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":null,"createdDate":"2018-06-30T20:15:01.038Z"}

Setting Up Callback Notifications

The following code samples can be used to set the callback URL, callback key, and subscribe you to three different event notifications.

HTTP Request

POST /api/callback

HTTP Headers

 Accept: application/json   Content-Type: application/json   Authorization: Basic api_key

Request Payload

 {   "url": "https://www.esl.com/callbackNotifications",   "key": "secureKey#1",   "events": [   "PACKAGE_CREATE",   "PACKAGE_DECLINE",   "PACKAGE_COMPLETE"   ]   }

For a complete description of each field, see the Request Payload table below.

Response Payload

 {   "url": "https://www.esl.com/callbackNotifications",   "key": "secureKey#1",   "events": [   "PACKAGE_CREATE",   "PACKAGE_DECLINE",   "PACKAGE_COMPLETE"   ]   }

The Result

After running your code, click Admin > Event Notification. You will see that your selected Event Notifications have been toggled on.

Request Payload Table

PropertyTypeEditableRequiredDefaultSample Values
urlstringYesNon/ahttps://www.esl.com/callbackNotifications
keystringYesNon/asecureKey#1