From the Trenches: Real-time updates in an embedded signing workflow
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 event query parameter to the returnUrl with 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 returnUrl is set to www.docusign.com, so when my embedded signer finishes signing and exits the session, they are redirected to my returnUrl with the event parameter signing_complete, indicating that they fully finished signing the envelope.
docusign.com/?event=signing_complete
Your 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.
