Status and Events

Your integration successfully sends or embeds signing requests. Envelopes are being signed. Great!

A common next step is to integrate envelope status and events with your application. Doing so enables your app to:

  • Display current envelope status to your users.
  • Alert your users as recipients view and sign their envelopes.
  • Automatically process signed documents. For example, automatically start other business processes that were waiting for documents to be signed. Record the fact that a document was signed, or the signed document itself, in other business systems.
  • Automatically process exceptional events: signing requests that are declined, envelopes that are voided or time-out. Alter the right people, automatically re-send the signing request as appropriate. Etc.

DocuSign offers multiple techniques for integrating transaction/envelope status and events with your application:

Webhook or Polling

The status of sent envelopes can be determined through the DocuSign webhook system or by polling. Webhooks are highly recommended: they provide your application with the quickest updates when an envelope’s status changes. In contrast, DocuSign limits polling for an envelope’s status to once every 15 minutes or less frequently.

When a webhook is used, DocuSign calls your application, via the URL you provide, with a notification XML message.

See the Webhook recipe for examples and live demos of using webhooks.

Webhook Options

The two webhook options, eventNotification and Connect use the same notification mechanism and message formats. eventNotification is used to create a webhook for a specific envelope sent via the API. Connect webhooks can be used for any envelope sent from an account, from any user, from any client. The Connect guide discusses the webhook notification message format.

eventNotification Webhooks

The Envelopes::create method includes an optional eventNotification object that adds a webhook to the envelope. eventNotification webhooks are available for all DocuSign accounts with API access.

Connect Webhooks

Connect can be used to create a webhook for all envelopes sent by some or all of the users in an account, either through the API or via other DocuSign clients (web, mobile, etc). Connect configurations are independent of specific envelopes. A Connect configuration includes a filter that may be used to limit the webhook to specific users, envelope statuses, etc.

Connect configurations may be programmatically created and managed using the ConnectConfigurations resource. Configurations can also be manually created and managed from the Administration tool. Select “Go to Admin” from the menu next to your picture on the DocuSign web app. Then see the Integrations/Connect section of the Admin tool. For repeatability, and to minimize support questions, creating Connect configurations via the API is recommended, especially for ISVs.

Connect is available for some DocuSign account types. Please contact DocuSign Sales for more information.

Polling for Current Status

Polling is available as an alternative to the Webhook system. Use the Envelopes::listStatusChanges method.

For any specific envelope, status requests are limited to once every 15 minutes or less frequently. Each request can specify the from/to times to that you’re interested in. To ensure that you don’t miss any changes, we recommend that you request overlapping times in your polls.

For example, your first polling request is at :05 after the hour and requests changes from :45 before the hour to :05 after (a 20 minute window).

Your next polling request is 15 minutes later (at :20) and requests status changes from the top of the hour (:00) to :20 (another 20 minute window).

Your last two polling requests are at :35 and :50 after the hour. They request status changes for the periods :15 to :35 and :30 to :50, respectively.

This technque may give you some duplicate information, but you won’t miss any changes.

Polling Rates are Checked

The number one reason for integrations to fail the DocuSign integration review process is excessive polling. Please ensure that your application polls the Signature platform no more than once every 15 minutes for an envelope’s status. It is okay to make polling requests more often than once per 15 minutes if the requests are for different envelopes.