Webhooks: Don't Poll Us, We'll Call You!

Your integration or app sends envelopes to recipients via email or by using embedded signing. Great!

A common next step for developers is to enable their integration to automatically determine the status of their envelopes--has the envelope been delivered?, signed?, declined?, completed?

By knowing the envelope’s and recipients’ statuses, your integration can handle each case appropriately. For example, consider these two scenarios:

• A recipient’s status becomes Delivered and is not changed to a status of Completed (signed). This indicates that the recipient received the envelope, and opened it on a mobile device, tablet, or web browser, but they haven't signed it yet! Your app might notify the sender of this situation to follow-up with the signer to see if there are any issues.
• An envelope's status becomes Completed. Your app could initiate actions or notify other databases that the envelope has now been signed. Your app could also download the signed document and certificate of completion for storage in a corporate archive system. (The documents will also be stored on the DocuSign system unless a purge policy has been configured.)

Both of the above scenarios depend on your app having current status information. How can your app learn about status changes?

Polling is an old-school technique that is still in use today. To poll, your app sets up an infinite loop that periodically requests envelope or recipient status from DocuSign on one or more envelopes. DocuSign limits polling frequency, so an envelope's status can be requested once every 15 minutes or less often. This restriction is implemented on all DocuSign production servers, without exception. This restriction does not apply while you’re developing your app in the DocuSign Developer Sandbox system, demo.docusign.net.

Polling has many disadvantages:

• On average, your app will learn about the envelope's new status 7.5 minutes (or more) after the event occurred, depending on your polling frequency.
• Your app's poller will spend most of its time learning nothing new, but will be consuming resources, including log space, process table space, and more.
• Your app must maintain a polling thread that should only stop when all of your envelopes have completed. It must be monitored and restarted as needed.
• Polling is a drag on the DocuSign system. We engineer the system to respond to polls, but doing so consumes energy and is completely unnecessary since the platform supports webhooks.

The answer is to stop polling. Use webhooks instead! The advantages of webhooks are:

• Webhooks enable the DocuSign platform to proactively notify your app when your envelope or any of its recipients statuses change.
• Your app receives the notifications much faster than the 7.5 minute average delay of polling. However, note that the messages are not delivered instantly after the event occurs. Customer UX threads should not wait for an incoming webhook message.
• Webhooks are the 21st century version of hardware interrupts: instead of wasteful polling, your app is notified when an event occurs.

Webhooks are easy to implement! See Part II of this post, Adding Webhooks to your Application for more information.