Skip to navigation
Platform 101Webhooks

Docusign Connect overview (webhooks)

View as Markdown

Docusign Connect is a webhook service that enables you to receive updates when specific triggering events occur in your eSignature workflows.

You can use a preset configuration to send envelope documents and data to Box, OneDrive, Salesforce, and eOriginal. The Docusign eSignature Admin Guide: Docusign Connect covers preset configurations.

  • Account- level Custom Connect configurations notify your listener for all subscribed events triggered by activity for that account. This enables you to configure webhook subscriptions that will send notification messages (in XML or JSON format) to your application whenever a selected trigger event occurs**.**
  • Recipient Connect configurations enable application notifications to be sent when one or more specific account users receive an envelope.
  • Envelope- level Connect configurations enable your listener to receive a notification when a selected trigger event occurs for specific envelopes.
  • Organization-level Connect configurations notify your listener for all subscribed events triggered by activity for any accounts in your organization. See Organization-Level Connect for details.

To use a Connect webhook, you must set up a web service (known as a webhook listener) that is available on the public internet. When a subscribed event occurs, Docusign Connect sends an HTTPS POST request to your webhook listener and your app uses the sent information to perform actions.

When to use Docusign Connect

Docusign Connect is especially useful:

  • When your application needs to quickly react to Docusign events; for example, sending a notice when the envelope is complete
  • When your application needs to start a workflow when a specific event happens
  • When you want a custom document archiving solution for completed envelopes

This can be directly relevant in many scenarios, including:

  • Business process engineering. Your app can use a webhook to detect when your envelopes are completed and act automatically upon the newly signed document. For example, your app could use an envelope-completed notification to update the order processing system, provision newly contracted services, or start other automated processes.
  • Write-back. Your app can provide up-to-date information about an envelope to other apps, such as the one that generated the envelope. For example, the envelope might include the signer’s address and enable the signer to update it if it is out of date. Your app can then write back the updated address and provide it to the original app.
  • Archiving. Your app can use the webhook notification as the trigger to store the envelope’s signed documents in a company-specific archiving system.
  • Business Intelligence (BI). Your app can use the webhook notification to update corporate databases and information systems with the envelope’s status and timing.

The following diagram shows each step in the process of sending a notification message to your app after a subscribed trigger event occurs.

Shows the steps in the Connect workflow

Retry mechanism

If message delivery for a given envelope fails, retries will be attempted using exponential back-off. The retry attempts will be made in the following sequence:

  • Five minutes later
  • 10 minutes later
  • 20 minutes later
  • 40 minutes later
  • One hour later
  • Two hours later
  • One day later
  • Once per day for a 15-day span

Advantages

The alternative to using webhooks to get events about updated status is polling: repeatedly making API calls to check the current status of an envelope or other object. Docusign strictly limits polling, preventing you from checking status more than once every 15 minutes per envelope or other API object. Your application will not be approved for use with Docusign if it violates the polling rules.

Docusign also implements API resource limits that help ensure the security and performance of the Docusign platform. You can avoid making unnecessary API calls that would count against your limits by using Connect webhooks to receive updates when they happen rather than polling.

Connect offers the following advantages over polling:

  • The returned information does not count against your API request limits because Docusign is sending it directly to you.
  • Messages are delivered to your listener only when your envelope status changes.
  • You avoid custom and cumbersome polling logic within your application that would have to manage the data returned and when to query again.
  • You get information when a state change occurs. For example, if you need to save a document immediately after the first signer signs it but before the second signer receives it, you can do that using Connect.

Video walkthrough

You can also see a video walkthrough of how to get status updates for an envelope using Connect:

Next steps