Set Up Callback Notifications

This guide will show you how to setup callback event notifications.

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 on your name in the toolbar and select “Admin”. From the menu on the left-hand side, select “Integration”. Below the API Key, you will see the Event Notification section.

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:

PACKAGE_ACTIVATE
PACKAGE_EXPIRE
PACKAGE_COMPLETE
PACKAGE_OPT_OUT
PACKAGE_CREATE
PACKAGE_READY_FOR_COMPLETE
PACKAGE_DEACTIVATE
PACKAGE_RESTORE
PACKAGE_DECLINE
PACKAGE_TRASH
PACKAGE_DELETE
DOCUMENT_SIGNED
ROLE_REASSIGN
SIGNER_COMPLETE
KBA_FAILURE
EMAIL_BOUNCE
PACKAGE_ATTACHMENT
SIGNER_LOCKED
PACKAGE_ARCHIVE
TEMPLATE_CREATE

You can find more information about the contents of each notification, here.

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

If you run 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 on your name in the toolbar and select “Admin”. From the menu on the left-hand side, select “Integration”. Below the API Key, you will see the Event Notification section.

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:

PACKAGE_ACTIVATE
PACKAGE_EXPIRE
PACKAGE_COMPLETE
PACKAGE_OPT_OUT
PACKAGE_CREATE
PACKAGE_READY_FOR_COMPLETE
PACKAGE_DEACTIVATE
PACKAGE_RESTORE
PACKAGE_DECLINE
PACKAGE_TRASH
PACKAGE_DELETE
DOCUMENT_SIGNED
ROLE_REASSIGN
SIGNER_COMPLETE
KBA_FAILURE
EMAIL_BOUNCE
PACKAGE_ATTACHMENT
SIGNER_LOCKED
PACKAGE_ARCHIVE
TEMPLATE_CREATE

You can find more information about the contents of each notification, here.

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 on your name in the toolbar and select “Admin”. From the menu on the left-hand side, select “Integration”. Below the API Key, you will see the Event Notification section.

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:

PACKAGE_ACTIVATE
PACKAGE_EXPIRE
PACKAGE_COMPLETE
PACKAGE_OPT_OUT
PACKAGE_CREATE
PACKAGE_READY_FOR_COMPLETE
PACKAGE_DEACTIVATE
PACKAGE_RESTORE
PACKAGE_DECLINE
PACKAGE_TRASH
PACKAGE_DELETE
DOCUMENT_SIGNED
ROLE_REASSIGN
SIGNER_COMPLETE
KBA_FAILURE
EMAIL_BOUNCE
PACKAGE_ATTACHMENT
SIGNER_LOCKED
PACKAGE_ARCHIVE
TEMPLATE_CREATE

You can find more information about the contents of each notification, here.

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 JSON Properties 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

JSON Properties

Property Type Editable Required Default Sample Value(s)
url string Yes No n/a https://www.esl.com/callbackNotifications
key string Yes No n/a secureKey#1