Polling vs. Webhooks
Polling Vs. Webhooks
When designing a DocuSign integration with your application or web site, one important factor that you need to consider is how to track your envelopes. DocuSign currently has two primary methods of accomplishing this task: polling and webhooks. In this blog post, I give you an introduction to both and I discuss some of the limitations and best practices around each approach.
Polling is a process by which you repeatedly make calls at a regular interval to the DocuSign eSignature API to check the status of your envelopes – to see who signed them, who didn’t, where there are issues, etc. The problem with this approach is that you don’t know when all recipients will sign the documents in an envelope.
Imagine this scenario… You are developing a dashboard that shows the status of each envelope your company sent to recipients. Let’s say you poll for the status of a specific envelope once per minute to update your dashboard, but one of the signers went on vacation for two weeks. Your system would poll 20,160 times (60 min/hr X 24 hrs/day X 14 days) – and that’s just for one envelope. If you extrapolate this for more than 400,000 DocuSign customers, if they all polled for the millions of envelopes sent, that would be a tremendous amount of potentially unnecessary network traffic – I’m not even going to attempt the math on that! ?
By contrast, webhooks is a popular push-notification technology whereby DocuSign sends you messages when there is a change in status. This means your systems don’t have to continually poll and create unnecessary network traffic, but it does mean a little extra work for you. The extra development work is because in order for you to receive the webhook messages sent by the DocuSign platform, you have to create a web listener that receives the messages and takes appropriate action. DocuSign’s webhook technology is called DocuSign Connect. or sometimes just referred to as Connect.
Let’s take a look at each in more detail…
First, let’s take a look at what status means because it applies to both polling and webhooks. It may seem obvious that status lets you know when someone signs a document. That’s true, but it is so much more than that. Status applies to both envelopes and recipients, so how about a quick crash-course on the relationship between those two. Take a look at this diagram:
A DocuSign envelope is where all the magic starts. An envelope contains one or more documents to be signed and one or more recipients (signers). Tabs are the fields in a document that specific recipients interact with. Examples of tabs (sometimes also referred to as tags or fields) include a signature tab (the location on a document where a recipient actually signs), text tabs (where a recipient may be prompted to enter information), etc. Tabs are not directly related to status, but they illustrate the point about why there can be more than one recipient, which is directly related to status.
DocuSign tracks the status in two ways:
- Recipient Status – applies to, as the name implies, the status of an individual recipient. This can be useful to determine, for example, which specific people have not signed a document in an envelope. For more information about recipient status values and what they mean, see Recipient Status.
- Envelope Status – applies to the envelope on the whole, considering all recipients as well. For example, an envelope that has a status of completed means that all recipients have signed all documents in an envelope. Therefore, depending on your system design, you may not have to query for recipient status. Additional information about envelope status values and their definition can be found in Create and Sending Envelopes.
With that knowledge tucked away in your mind, let’s dive into more of the technical differences between polling and webhooks.
To help prevent unnecessary network traffic (as I described in a scenario above), DocuSign limits polling activity in two ways:
- By account – Each account, by default, is limited to 1,000 API calls per hour. This is known as an Hourly Invocation Limit. If your DocuSign integration requires a higher value, reach out to your Account Manager to discuss having this limit increased. We impose this limit to help manage the potential of poorly-written code that loops excessively or other anomalies that run amok. If your account reaches the Hourly Invocation Limit, access to our eSignature API will be cut off until the API call counter resets at the top of the next hour.
- By unique URI – Specific API endpoint calls are referenced as unique URIs (Uniform Resource Identifiers). URIs can be thought of as the part of an endpoint’s path that does not include a protocol or server name. Here are some examples:
- In the top right-hand corner click your picture, then click Go to Admin. It looks like this: