Callback Event Notifications: Why Poll? We'll Call You!
Once you have your integration or application up and running, you might be wondering... what's next? In other words, your application sends transactions (i.e. packages) to recipients via email or by using embedded signing. Great!
The next logical step is to enable your integration to automate post-esignlive tasks. Consider these two scenarios:
- Your transaction status becomes Completed. Your app could download the signed documents upon completion of the transaction for storage in a corporate database.
- Your recipient uploaded an attachment you requested. Your app could notify you of such an event in order for the attachment to be reviewed.
One way to go about retrieving these information would be to setup some polling mechanism. For example, you could setup your app to periodically check the status of one or more transactions. However, polling has many disadvantages:
- Your app will spend most of its time learning nothing new. Say you send a transaction for signing and it only gets completed a week later with your app polling the status of the transaction once an hour, you would retrieve that your transaction is not yet completed 167 times... Yikes!
- It's a pain on the eSignLive servers. Polling the status of one transaction every hour is not the end of the world. But realistically, you will make more than one transaction at time. If each of our customers had 100 pending transactions and polled the status for each one every 15 minutes, this would quickly become extremely inefficient and would put a huge load on the eSignLive system.
The alternative to polling would be to use callback event notifications. Essentially, when an event happens (i.e. transaction completed, attachment uploaded, etc.), a notification is sent in the form of an HTTP POST request to the registered URL in your eSignLive account. The POST request contains relevant information about the event, which makes it possible for your app to act accordingly. You can choose which events you would like to receive payloads for. Only subscribing to the specific events you plan on handling is useful for limiting the number of HTTP requests to your server. You can change the list of subscribed events through the API or UI anytime.
Callbacks offer many advantages. Mainly, it eliminates the need of wasteful polling. You get useful information as they happen.
Configuring Callback Event Notifications
Before the eSignLive system can notify you of an event, you must first register to be notified in case of an event. With a single request, an account can have one or more events linked to a URL. A newly registered event notification will take up to 5 minutes following its registration to be active. Developers can also configure Basic Authorization to make callback notifications more secure in the form of an optional callback key, which is sent in plain text as a header when making a callback. The callback key is encrypted when saved. Though, to be truly secure, you should use callback keys only over HTTPS.
You can follow this feature guide on how to register for callback event notifications.
Configuring Your Application
Your listener URL is a URL that your application receives incoming requests on (e.g. https://www.yourcompany.com/events). When one of the registered events occur, the eSignLive platform will make a POST request to your listener, at the URL you provided, with the relevant data. Thus, this means that your listener URL must be publicly accessible to enable the eSignLive platform to call it.
You can follow these blogs on how to create a simple callback listener:
If you have questions regarding this blog or anything else concerning integrating eSignLive into your application, visit the developer community forums: https://developer.esignlive.com. That's it from me. Thank you for reading! If you found this post helpful, please share it on Facebook, Twitter, or LinkedIn.
Haris Haidary
Junior Technical Evangelist
LinkedIn | Twitter
