OneSpan Sign Developer: Callback Event Notification – Part 2

In this first part of this blog series, we reviewed the potential uses of different event notifications and the recommended workflows by setting up callback listener whenever you need to poll transaction, signer, or any other bit of info. 

In this blog, we will show you the common process of handling a callback request and all the interesting technical details regarding callback event notifications. Without further ado, let’s started!

Register for Event Notifications

Before OneSpan Sign can notify you of an event, you must first register your callback URL or an optional callback key as well as specifying which events require notification. You can follow our Set up Callback Notifications guide on how to register for event notifications programmatically or simply do it through the web portal on the Integration tab on the Admin page as shown below.

Create a Callback Listener

You’re now ready to create a webhook listener! The diagram below shows you all the necessary steps in handling a post request. From there, we’ll explain the technical details accordingly. This is a general process that can be applied to any programming language or web framework you are currently developing with.

Callback Listener Point 1

First, you need a public URL for OneSpan Sign to call. Just for the test purpose, you can get a temporary one by Ngrok.
So when an event occurs, such as when a transaction has been completed, OneSpan Sign sends an HTTP POST request to the URL registered in this first section. 

Callback Listener Point 2 & 3

Remember the callback key you set in the registry? This secret token is used to identify that the POST call was actually from OneSpan Sign. This helps confirm that you are not receiving spoof calls.
The callback key you registered is passed through the Authorization header as “Basic {callbackKey}”.  
Once you validate that the request contains your shared secret, you can continue to process the request.

Callback Listener Point 4

Event information is passed at the request body, which includes a JSON object that contains type and the data associated with that event.
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"}

To note that, the body of each call may vary based on the notification event type.

Callback Listener Point 5 & 6

According to the event name, you can distribute the task to stub functions to deal with it as per your business logic. This was recommended in the first part of this blog series. If your service function has a complex workflow and will consume the request for a long time, it’s better that you use an asynchronous method to avoid causing timeout error. For the current implementation, the callback timeout setting was 20 seconds  and could vary between different instances.

Then, return an HTTP status code 200 back to OneSpan Sign indicating that you’ve successfully received the callback. 

What if I missed a notification?

Missing a notification is a possible risk when using event notification mechanism. 

When a callback fails, an email is sent out. From version 11.21, that email has been improved to include the reason for the failure. For example, if there’s a timeout exception, a “resource can’t be found” error, or other error code, these emails can help troubleshoot the cause of the failure. 

What’s more, you can actively poll your events every 6, 12, or 24 hours as a backup to reduce the losses in case a notification was missed.

Above was all the necessary technical knowledge you need to know in order to setup a callback listener. In the next few blogs, we will demonstrate some sample projects using different languages and frameworks following the steps we mentioned here.

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!

OneSpan Developer Community

Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.

Join Today