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.

Before You Begin

Before getting started, there are a couple things that will be useful to know before setting one of these up and testing.

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 (Undefined variable: General.eSignLive_Product Name).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 (Undefined variable: General.eSignLive_Product Name).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 (Undefined variable: General.eSignLive_Product Name)'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:

  • "bounced"
  • "complaint"
  • "ooto" (out-of-the-office)
  • "blacklisted"

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

The Code

Below are snippets code that sets the callback URL, callback key, and subscribes you to three different event notifications. You can get complete sample code from the Developer Community Code Share, here.

The first step is to create your EslClient with your API_KEY and API_URL (remember to use apps instead of sandbox for production). 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 );

Then, you 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.

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

Get the Code

Callback event notifications allow you to be automatically notified of events pertaining to a package (transaction in the new UI). Upon a specific event, the system will automatically issue a message to a destination you choose.

Before You Begin

Before getting started, there are a couple things that will be useful to know before setting one of these up and testing.

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 (Undefined variable: General.eSignLive_Product Name).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 (Undefined variable: General.eSignLive_Product Name).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 (Undefined variable: General.eSignLive_Product Name)'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:

  • "bounced"
  • "complaint"
  • "ooto" (out-of-the-office)
  • "blacklisted"

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

The Code

Below are snippets of code that sets the callback URL, callback key, and subscribes you to three different event notifications. You can get complete sample code from the Developer Community Code Share, here.

The first step is to create your EslClient with your API_KEY and API_URL (remember to use apps instead of sandbox for production). Be sure to change the API_KEY, API_URL, URL, and KEY to your own values.

string API_KEY = "YOUR_API_KEY";
string API_URL = "https://sandbox.esignlive.com/api";
string URL = "http://my.url.com";
string KEY = "myCallbackKey";
EslClient eslClient = new EslClient( API_KEY, API_URL );

Then, you 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.

eslClient.EventNotificationService.Register(EventNotificationConfigBuilder.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

Get the Code

Callback event notifications allow you to be automatically notified of events pertaining to a package (transaction in the new UI). Upon a specific event, the system will automatically issue a message to a destination you choose.

Before You Begin

Before getting started, there are a couple things that will be useful to know before setting one of these up and testing.

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 (Undefined variable: General.eSignLive_Product Name).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 (Undefined variable: General.eSignLive_Product Name).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 (Undefined variable: General.eSignLive_Product Name)'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:

  • "bounced"
  • "complaint"
  • "ooto" (out-of-the-office)
  • "blacklisted"

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

The Code

This segment of the guide only shows snippets of code. You can download the full sample code from the Developer Community Code Share, here.

Below is a sample request that performs a POST request to set the callback URL, callback key, and subscribes you to three different event notifications. Be sure to change the API_KEY, URL, and KEY to your own values. You can also add more notification subscriptions from the table of options, above.

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

Get the Code

Request Payload

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