The ScenarioIn many situations, regardless if the envelope was sent via an API integration or manually sent from the eSignAnyWhere Web UI, a serverside postprocessing step should be imlpemented which is performing some activities after an envelope was completed, i.e. after all defined activities such as signing have been completed on all document(s) of a business case. For that scenario, eSignAnyWhere allows to implement callback handlers, which are web services. These web services are invoked automatically, based on webhooks defined by the sender or the admin of an organization. This story contains a summary of well known use cases where callback handlers help to solve common tasks, and describes best practices in implementing such. We recommend to read the story "Retrieving the User API Token via OAuth" before continuing with this story, when you intend to cover situations where envelopes are sent via WebUI. |
Implementation Best-PractisesValidate Input Parameters before processingKeep in mind that the callback could have been fired from malicious sources. Therefore, validate all input parameters received via the callback. This includes:
Asynchronous Callback HandlingWhenever a callback is received, the callback handler should just note down the event and return to eSignAnyWhere that the callback event was successfully noted down. But the event processing should be done asymetric, e.g. in a background service call. If the implementation is done in the callback handler directly (in a synchronous processing), you may run in situations where the handling of a callback takes longer than the standard network timeouts configured on eSignAnyWhere side. When eSignAnyWhere receives a timeout due to longer ongoing processing activities in a callback handler, eSignAnyWhere is noting down the failure and starting a retry mechanism. In standard configurations, there are up to 30 retries of the callback. This may lead to situations where the callback processing of the same envelope, for the same event, is done up to 30 times or even higher with different system configuration. In case a callback handler is e.g. downloading signed documents from eSignAnyWhere, and uploading the documents to a document management system, an improper integration may result in storing the same document multiple times in the document management system. Therefore, note down in a database which event was received, and for which envelope (or workstep, in case of WorkstepEventCallbacks). Let the callback handler return a HTTP 200 directly after the event was noted down in persistent storage. Implement a periodic serverside job which gets activated on a timed schedule, or on adding entries to the noted down events table. The serverside job then should asynchronously perform the necessary actions. Authentication retrieved via OAuth 2.0 Code Grant & note down the sender userIn some scenarios, e.g. those where the envelope is sent from WebUI, a callback handler implementation needs to deal with envelopes sent by different senders. While in scenarios where envelopes are sent via API, the sender's API key is well known at that time already (obtained via OAuth code or configuration), the user specific API key is unknown when sending via WebUI. We do therefore recommend to implement a BeforeSendRedirect page that implements the OAuth Code Grant flow, to obtain the consent from the sender to grant access via OAuth. The implementation then can retrieve, if unknown for the sender, the API key. We recommend to store the obtained API key per user in the database, under consideration of OWASP recommendations on how to persist passwords (e.g. encrypt them). Furthermore, note down in a different table which envelope (by envelopeId) was sent by which sender, as this information is necessary for the callback handler implementation. In the callback handler implementation, do a lookup based on envelopeId which user was the sender; and then authenticate with the apiKey noted down for the sender. In case of an authentication error, trigger an error handling procedure to obtain a new apiKey (read below). Alternative techniques such as using teams or using organization keys, are listed as "not recommended" for the following reasons:
Error HandlingDon't forget to think about proper error handling in your asynchronous callback handler. A callback handler is a serverside job which does not involve the user typically. But for situations where an error occured, think if the sender or an administrator needs to be involved. If a person has to be involved, as we are talking about automatic serverside processing, think about a proper way to trigger a human interaction - probably with some user specific or administrative UI of the callback handler, and a notification sent via e-mail. Typical scenarios you might consider in the implementation:
|
Example architecture diagram with call sequenceThe diagram shows how a callback handler could push data to a document management system (DMS). Any other integration system that needs to process signed documents could be in place of the "Customer DMS" instead. |
Following steps describe the implementation in detail:
Once completed, the callback handler implementation (i.e. the asynchronous service) should delete the envelope from eSignAnyWhere when it is not used in eSignAnyWhere any longer and after the document, the audit trail and other legal evidence documents have been successfully transferred to a permanent storage outside eSignAnyWhere. Alternatively, a data retention job can be configured on the organization to perform an automatic cleanup. But note that the retention job would not identify/stop when the transfer to the permanent storage failed. |