Blog
Home/

Building best practices webhook listeners, part 1: Webhook listeners and Connect

Larry Kluger
Larry KlugerDocuSign Lead Product Manager for Partner Platforms
    • Connect settings
    • Coming soon

Table of contents

By Larry Kluger and Joey Peng

Docusign Connect implements webhooks that enable applications to subscribe to be notified when an envelope’s status is updated. About half of all Docusign customer and partner integrations use Connect to track envelope status, collect metadata, and take action after envelopes are completed.

Applications subscribe to Connect at the account level: any time the status of an envelope sent by any user in your account is updated, a webhook notification can be sent. Connect also offers event subscriptions for individual envelopes, which enable you to subscribe to receive webhook notifications each time a status event occurs for the specific envelope.

For both account and envelope webhook subscriptions, you can choose which envelope and recipient status changes should trigger a notification to your application. For example, you can choose to be notified when the envelope as a whole is completed and fully signed, or whenever an individual recipient signs (or both).

Because  Connect notification messages are delivered as HTTPS POST requests, it is relatively easy to build a Connect “listener” to receive and process messages. In this series of blog posts, we’ll discuss best practices, practical techniques, and examples for building robust webhook listeners that will work well and scale as needed.

Connect settings

We suggest using the default Connect settings for your Connect subscriptions, with the following exceptions. Note that your specific settings may be different, depending on your use case.

Setting Name

Recommended Value

Description

Include Basic Authentication Header

On

Use Basic Authentication as a first line of defense to prevent attacks and “door knocking” against your server. Remember to change the password periodically.

HMAC

On

Use the

HMAC feature

to cryptographically guarantee that the notification messages were sent by Docusign and were not altered in transit. HMAC secret keys are set at the account level. In addition, enable HMAC for each Connect subscription.

SIM (Send Individual Messages)

On

The newer SIM queuing algorithm is recommended for all new Connect applications. SIM is set at the account level using the

Account

>

Updates

screen.

Include Document PDFs and Certificate of Completion settings

Off

Including either documents or certificates of completion in the notification messages should be considered very carefully. These features cause the size of the notification messages to balloon from a few thousand bytes to many megabytes. It is then common for large notification messages to cause problems throughout the listener’s webstack, leading to brittle and unreliable listeners.

Instead of including the documents, your application can download them from Docusign as needed via the API.

Time Zone Information

On

Enables better parsing of timestamps.

Envelope Voided Reason

On

Useful for tracking voided envelopes.

Sender Account as Custom Field

On

Many larger customers use more than one Docusign account. Including the account ID in the notification message enables more generalized webhook worker applications.

Document Fields

On

The relatively small size of this data enables it to be included in the notification messages. If your envelopes can include very large numbers of envelope fields, then turn this setting off.

Associated Users

As few as possible

Only set webhooks for the users whose envelopes you need to monitor.

Trigger events

As few as possible

Subscribe to the minimal set of events as needed by your application and use case.

Coming soon

In the next post in this series, we’ll discuss the recommended software architecture for a Connect listener.

Larry Kluger
Larry KlugerDocuSign Lead Product Manager for Partner Platforms

Larry Kluger has over 40(!) years of tech industry experience as a software developer, developer advocate, entrepreneur, and product manager. An award-winning speaker with a 48K StackOverflow reputation, he enjoys giving talks and helping the ISV and developer communities.

Twitter: @larrykluger

LinkedIn: https://www.linkedin.com/in/larrykluger/

More posts from this author

Related posts

Discover what's new with Docusign IAM or start with eSignature for free

Explore Docusign IAMTry eSignature for Free
Person smiling while presenting