Has my envelope been signed?

A common issue when developing with Docusign APIs is programmatically determining if an  envelope and its documents have been signed yet. There’s a wrong way and two right ways to accomplish this. Let’s look at each of them.

The wrong way

If your application uses embedded signing, then Docusign will redirect the signer’s browser back to your application after the signer has finished using the signing ceremony. The redirect URL will include an event query parameter that can have values including signing_complete, cancel, and decline. See the documentation for the complete list.

But there is no guarantee that the redirect to your application was initiated by Docusign! A bad actor could spoof your application with a false event parameter. Therefore, the event query parameter should only be used as a hint. Don’t make any business decisions because of it.

An additional issue to consider is the difference between a signer signing the envelope and the envelope’s overall status of complete. In the Docusign system, a completed envelope has been signed by all relevant signers, copies have been sent as directed by the envelope’s sender, payments have been collected, etc. As a developer, you will typically want to wait for the envelope to reach a status of complete, versus one of the recipients signing the envelope.

The right ways

Either of the following techniques can be used to determine an envelope’s status authoritatively.

Polling

You can poll Docusign to check the status of an envelope. Polling is allowed no more frequently than once every 15 minutes. To receive the status for a specific envelope, use the Envelopes::get API method. To receive the status of multiple envelopes with one call, use the Envelopes::listStatus or Envelopes::listStatusChanges methods.

Webhooks

You can register a callback URL, called a webhook, with Docusign. This technique is preferred to polling because your application will be notified of the status change faster than polling allows. A webhook is also less of a processing burden on your application. Docusign enables you to register a webhook at the account level via Docusign Connect, or for an individual envelope by using the eventNotification attribute.

Webhooks from behind the firewall

Webhooks usually require the receiving application to be accessible on the public Internet. This can be an expensive proposition because enabling your server to be reached from the public Internet requires additional information security hardening and maintenance.

An easier alternative is to have the webhook notification delivered to a serverless function from a Platform as a Service (PaaS) cloud vendor (such as AWS or Azure; there are many others), queued, and then retrieved from behind the firewall by your application. Depending on the vendor, the PaaS cost is free or low, and the benefits of receiving the notifications from behind an unmodified firewall are high. Check out the code examples for this pattern.

Conclusion

Signatures are important. Use the Docusign eSignature API features discussed in this post to ensure that you’re always making business decisions based on correct data.

See you in San Francisco!

Please join me and my colleagues for a great developer day at the Docusign Momentum conference on March 4. Registration for developers is free!

Additional resources

Developer posts about Connect webhooks:

• Building best practices webhook listeners

• Connect HMAC signatures for added security

• Connect basic authentication support

• Securing your Connect webhook listener

Additional developer resources:

• Docusign Developer Center

• Docusign for Developers on YouTube

• @DocuSignAPI on Twitter

• Docusign for Developers on LinkedIn

• Docusign Developer Newsletter