Setting Up Callback Notifications
- 22 Nov 2024
- 18 Minutes à lire
- SombreLumière
- PDF
Setting Up Callback Notifications
- Mis à jour le 22 Nov 2024
- 18 Minutes à lire
- SombreLumière
- PDF
Résumé de l’article
Avez-vous trouvé ce résumé utile ?
Merci pour vos commentaires
Java SDK
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
sessionUserfields is 255 characters.The maximum size for all
packageIdfields is 255 characters.The
sessionUserfield 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 |
|---|---|---|
| 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. |
|
| A document was signed, or Consent and/or Disclosure Agreements were accepted. |
|
| A document was viewed. |
|
| An email has bounced. The bounce types are the following:
For more information, see our list of templates. |
|
| The transaction/documents have successfully been deposited to eOriginal. |
|
| The transaction/documents are unable to be deposited to eOriginal in some unrecoverable way. Note that the reason for the failure may vary. |
|
| The transaction/documents are unable to be deposited to eOriginal in some unrecoverable way, and there will be additional automated retry attempts to deposit the documents. |
|
| There has been a KBA Authentication failure. |
|
| 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. |
|
| A callback notification indicates that a package has been archived. |
|
| A callback notification indicates that a signer has uploaded an attachment. |
|
| 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. |
|
| 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. |
|
| A package's status has changed from SENT to DRAFT. |
|
| 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. |
|
| A package has been deleted from the OneSpan Sign.com system. |
|
| A package has exceeded its expiration date. |
|
| A package has been marked as DO_NOT_AUTOCOMPLETE. An action by the sender will be required to complete the package. |
|
| A package was trashed, but is being moved back to the state it was in before it was trashed. |
|
| A package was moved to the trash folder in OneSpan Sign's Inbox (status = TRASH). |
|
| 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. |
|
| A signer has delegated their signature to another signer. When this happens, OneSpan Sign creates a newrole with a new signer. It is a good idea at this 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. |
|
| A signer has completed signing all documents. |
|
| A callback notification indicates that a signer has been locked out due to repeated SMS/Q&A authentication failures. |
|
| A callback notification indicates that a template has been created. |
|
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.
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 );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, click Admin > Event Notification. You will see that your selected Event Notifications have been toggled on.
.NET SDK
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
sessionUserfields is 255 characters.The maximum size for all
packageIdfields is 255 characters.The
sessionUserfield 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 |
|---|---|---|
| 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. |
|
| A document was signed, or Consent and/or Disclosure Agreements were accepted. |
|
| A document was viewed. |
|
| An email has bounced. The bounce types are the following:
For more information, see our list of templates. |
|
| The transaction/documents have successfully been deposited to eOriginal. |
|
| The transaction/documents are unable to be deposited to eOriginal in some unrecoverable way. Note that the reason for the failure may vary. |
|
| The transaction/documents are unable to be deposited to eOriginal in some unrecoverable way, and there will be additional automated retry attempts to deposit the documents. |
|
| There has been a KBA Authentication failure. |
|
| 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. |
|
| A callback notification indicates that a package has been archived. |
|
| A callback notification indicates that a signer has uploaded an attachment. |
|
| 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. |
|
| 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. |
|
| A package's status has changed from SENT to DRAFT. |
|
| 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. |
|
| A package has been deleted from the OneSpan Sign.com system. |
|
| A package has exceeded its expiration date. |
|
| A package has been marked as DO_NOT_AUTOCOMPLETE. An action by the sender will be required to complete the package. |
|
| A package was trashed, but is being moved back to the state it was in before it was trashed. |
|
| A package was moved to the trash folder in OneSpan Sign's Inbox (status = TRASH). |
|
| 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. |
|
| A signer has delegated their signature to another signer. When this happens, OneSpan Sign creates a newrole with a new signer. It is a good idea at this 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. |
|
| A signer has completed signing all documents. |
|
| A callback notification indicates that a signer has been locked out due to repeated SMS/Q&A authentication failures. |
|
| A callback notification indicates that a template has been created. |
|
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.
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);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, click Admin > Event Notification. You will see that your selected Event Notifications have been toggled on.
REST API
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
sessionUserfields is 255 characters.The maximum size for all
packageIdfields is 255 characters.The
sessionUserfield 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 |
|---|---|---|
| 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. |
|
| A document was signed, or Consent and/or Disclosure Agreements were accepted. |
|
| A document was viewed. |
|
| An email has bounced. The bounce types are the following:
For more information, see our list of templates. |
|
| The transaction/documents have successfully been deposited to eOriginal. |
|
| The transaction/documents are unable to be deposited to eOriginal in some unrecoverable way. Note that the reason for the failure may vary. |
|
| The transaction/documents are unable to be deposited to eOriginal in some unrecoverable way, and there will be additional automated retry attempts to deposit the documents. |
|
| There has been a KBA Authentication failure. |
|
| 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. |
|
| A callback notification indicates that a package has been archived. |
|
| A callback notification indicates that a signer has uploaded an attachment. |
|
| 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. |
|
| 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. |
|
| A package's status has changed from SENT to DRAFT. |
|
| 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. |
|
| A package has been deleted from the OneSpan Sign.com system. |
|
| A package has exceeded its expiration date. |
|
| A package has been marked as DO_NOT_AUTOCOMPLETE. An action by the sender will be required to complete the package. |
|
| A package was trashed, but is being moved back to the state it was in before it was trashed. |
|
| A package was moved to the trash folder in OneSpan Sign's Inbox (status = TRASH). |
|
| 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. |
|
| A signer has delegated their signature to another signer. When this happens, OneSpan Sign creates a newrole with a new signer. It is a good idea at this 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. |
|
| A signer has completed signing all documents. |
|
| A callback notification indicates that a signer has been locked out due to repeated SMS/Q&A authentication failures. |
|
| A callback notification indicates that a template has been created. |
|
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/callbackHTTP 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
Property | Type | Editable | Required | Default | Sample Values |
|---|---|---|---|---|---|
url | string | Yes | No | n/a | https://www.esl.com/callbackNotifications |
key | string | Yes | No | n/a | secureKey#1 |
Cet article vous a-t-il été utile ?