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.

Capture

As you will see, this area is completely blank (unless you have already set this up).

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
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_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_OPT_OUT A recipient has opted out of signing a package electronically, 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_OPT_OUT",

"sessionUser": "...",

"packageId": "...",

"message": "opt-out reason", (max 4000 chars)

"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" }

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" }

ROLE_REASSIGN A signer has delegated their signature to another signer.

{ "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" }

KBA_FAILURE There has been a KBA Authentication failure.

{ "name": "KBA_FAILURE",

"sessionUser": "...",

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

"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" }

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" }

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" }

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

{ "name": "PACKAGE_ARCHIVE",

"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"}
Signer 1 opt out:
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"PACKAGE_OPT_OUT","sessionUser":"b5381b13-991e-4179-9f9b-d4e1ec9d06bb","packageId":"J5tyJalzG49hmDho5b9JdG61T7M=","message":"the personal info is not correct","documentId":null,"createdDate":"2018-06-30T20:16:29.763Z"}

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, this is the result you will see if you go back to the Event Notification area in the UI, as shown in the Before You Begin section.

Capture

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.

Capture

As you will see, this area is completely blank (unless you have already set this up).

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
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_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_OPT_OUT A recipient has opted out of signing a package electronically, 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_OPT_OUT",

"sessionUser": "...",

"packageId": "...",

"message": "opt-out reason", (max 4000 chars)

"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" }

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" }

ROLE_REASSIGN A signer has delegated their signature to another signer.

{ "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" }

KBA_FAILURE There has been a KBA Authentication failure.

{ "name": "KBA_FAILURE",

"sessionUser": "...",

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

"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" }

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" }

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" }

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

{ "name": "PACKAGE_ARCHIVE",

"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"}
Signer 1 opt out:
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"PACKAGE_OPT_OUT","sessionUser":"b5381b13-991e-4179-9f9b-d4e1ec9d06bb","packageId":"J5tyJalzG49hmDho5b9JdG61T7M=","message":"the personal info is not correct","documentId":null,"createdDate":"2018-06-30T20:16:29.763Z"}

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, this is the result you will see if you go back to the Event Notification area in the UI, as shown in the Before You Begin section.

Capture

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.

Capture

As you will see, this area is completely blank (unless you have already set this up).

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
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_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_OPT_OUT A recipient has opted out of signing a package electronically, 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_OPT_OUT",

"sessionUser": "...",

"packageId": "...",

"message": "opt-out reason", (max 4000 chars)

"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" }

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" }

ROLE_REASSIGN A signer has delegated their signature to another signer.

{ "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" }

KBA_FAILURE There has been a KBA Authentication failure.

{ "name": "KBA_FAILURE",

"sessionUser": "...",

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

"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" }

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" }

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" }

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

{ "name": "PACKAGE_ARCHIVE",

"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"}
Signer 1 opt out:
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"PACKAGE_OPT_OUT","sessionUser":"b5381b13-991e-4179-9f9b-d4e1ec9d06bb","packageId":"J5tyJalzG49hmDho5b9JdG61T7M=","message":"the personal info is not correct","documentId":null,"createdDate":"2018-06-30T20:16:29.763Z"}

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, take a look at the Request Payload section 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, this is the result you will see if you go back to the Event Notification area in the UI, as shown in the Before You Begin section.

Capture

Request Payload

PropertyTypeEditableRequiredDefaultSample Value(s)
urlstringYesNon/ahttps://www.esl.com/callbackNotifications
keystringYesNon/asecureKey#1