From the Trenches: Real-time updates in an embedded signing workflow
Discover how to get real-time updates from your eSignature REST API embedded signing workflows by using the returnUrl's event status parameter.
Embedded recipients are the most common in-session recipient type used in envelopes sent via API. Embedded signing enables recipients to view and sign documents directly through your app or website without having to switch contexts to email. In this sense, your application hosts a signing session: no physical presence required or captured in the Certificate of Completion. You can embed Docusign functionality in your app using standard embedded signing, or by using elastic signing functionality with the Docusign Click API.
In an embedded signing scenario, after the recipient completes or ends the signing ceremony, Docusign redirects the user's browser back to your app via the returnUrl that you supply.
The recipient can be shown a status page depending on whether they finished signing or not. As a result, Docusign Support has received a few cases from developers discussing the best way to have real-time status updates pushed back to their application when the embedded signing session is finished.
Docusign Connect, our webhook service, has been a popular go-to answer to address this. However, Docusign Connect is unable to guarantee real-time updates. I will discuss the issues with relying on Connect as well as the approach that Docusign Developer Support recommends.
Problems associated with using Docusign Connect for real-time updates
Docusign Connect can publish messages based on certain event triggers to a listener on your end. Once an event is triggered, Docusign Connect will collect all the information chosen for the event and send it through to your listener. The time it takes to transmit the message to your listener plus any additional processing required on your listener’s end could add a delay from anywhere between 20 seconds to a few minutes. This could lead your user interface to be blocked until this process finishes.
The alternative: The event status parameter
Docusign appends an eventquery parameter to the returnUrlwith the outcome of the signing ceremony. This parameter takes different values based on the event that caused the signing session to end. As an example, take a look at the example below. My returnUrlis set to www.docusign.com, so when my embedded signer finishes signing and exits the session, they are redirected to my returnUrlwith the eventparameter signing_complete, indicating that they fully finished signing the envelope.
docusign.com/?event=signing_completeYour application can use this parameter to display a summary page for your signers. These are the various values that the event query parameter can take, along with the triggers for each of them.
access_code_failed: Recipient used incorrect access code.cancel: Recipient canceled the signing operation, possibly by using the Finish Later option.decline: Recipient declined to sign.exception: A system error occurred during the signing process.fax_pending: Recipient has a fax pending.id_check_failed: Recipient failed an ID check.session_timeout: The session timed out. An account can control this timeout by using the Signer Session Timeout option.signing_complete: The recipient completed the signing ceremony.ttl_expired: The Time To Live token for the envelope has expired. After being successfully invoked, these tokens expire after five minutes.viewing_complete: The recipient completed viewing an envelope that is in a read-only/terminal state, such as completed, declined, or voided.
Because a user can cancel redirection, close their browser after signing, or spoof the landing URL, we recommend that your application confirm the status of the envelope through an Envelopes:get request or a Docusign Connect event.We recommend that you test this out in your demo environment to make sure that this would work for your application.
Additional resources
Karan Kaushik began his Docusign career in January 2022. As a front-line developer support engineer, Karan enjoys working on complex technical problems. He is passionate about using technology to make people's day-to-day lives easier and simpler, leveraging his array of experience across information technology, cloud operations, and software development.
Related posts
Discover what's new with Docusign IAM or start with eSignature for free
