OneSpan Sign Developer: Callback Event Notification – Part 1

Duo Liang, April 10, 2019

Imagine you are developing a custom transaction dashboard integration with OneSpan Sign. To refresh the status of your transactions, there is only one viable option.

In order to facilitate your integration and keep in line with best programming practice, OneSpan Sign provides a web hook mechanism called ”callback event notification.” As one of the most widely used features, callback event notifications allow you to be automatically notified of events pertaining to a package.

In this blog, we’ll walk through all 20 events you can register and categorize them into several parts to provide a better idea of what kind of information event notifications can deliver.

Package Status Change:

PACKAGE_CREATE (DRAFT)
TEMPLATE_CREATE (DRAFT)
PACKAGE_ACTIVATE (SENT)
PACKAGE_DEACTIVATE (DRAFT)
PACKAGE_COMPLETE (COMPLETED)
PACKAGE_DECLINE (DECLINED)
PACKAGE_OPT_OUT (OPTED_OUT)
PACKAGE_EXPIRE (EXPIRED)
PACKAGE_ARCHIVE (ARCHIVED)

Package Manipulation Actions:

PACKAGE_TRASH (Trash Action)
PACKAGE_RESTORE (Restore Action)
PACKAGE_DELETE (Delete Action)

The Events listed above cover all possible package and template status changes, which is an important use case for event notification. A potential solution for building a transaction dashboard that reflects the status change in real time could be:

(1) You set up a database to store all created package information.
(2) Once any of callbacks above are triggered, you can update the package status at your database.
(3) Call stub function if you have your own business logic based on the specific status change.
(4) For your front end users, you can render your front end page by polling your local database.
(5) Every 6, 12, or 24 hours, your application can poll the latest updated packages and update your local database as a backup in case you’ve missed any callback requests.

In this way, you can avoid frequently polling latest information and significantly reducing OneSpan Sign’s server load.

If you are not familiar with the package status, check out our recent blog post: Lifecycle of a Package.

Signing Status Change:

DOCUMENT_SIGNED
SIGNER_COMPLETE

With the DOCUMENT_SIGNED event, you will receive real-time updates with important information whenever a signer signs a document.

With the SIGNER_COMPLETE event and an integration with local database, your application would know how many signers have completed or are left to sign. This event will help trigger the right signing timing when a specific signing sequence is necessary.

Interesting Events during Signing Ceremony

SIGNER_LOCKED
KBA_FAILURE
EMAIL_BOUNCE
PACKAGE_READY_FOR_COMPLETION

When these events occur, your package sender should be informed and take corresponding actions to continue the signing process.

ROLE_REASSIGN
PACKAGE_ATTACHMENT

The two events above tell your application that the package contents get updated during the signing phase.

Create a Callback Listener

So far, we have reviewed event notifications and the recommended workflow for poll transactions, signers, or any other bit of info. In next few blogs of this series, we’ll introduce the event notifications in a technical and detailed manner and demonstrate recommended processes for handling a callback in different programming languages.

All this information is also available on our Create a Callback Event Notification Listener page.

If you have any questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the Developer Community Forums. Your feedback matters to us!

Duo Liang

Duo Liang is a Technical Evangelist and Partner Integrations Developer at OneSpan where he creates and maintains integration guides and code shares, helps customers and partners integrate OneSpan products into their applications, and builds integrations within third party platforms.

OneSpan Blog