Building best practices webhook listeners, part 1: Webhook listeners and Connect
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
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 has over 40 years of tech industry experience as a software developer, developer advocate, entrepreneur, and product manager. An award-winning speaker prominent StackOverflow contributor, he enjoys giving talks and helping the ISV and developer communities.
Twitter: @larrykluger
LinkedIn: https://www.linkedin.com/in/larrykluger/
Discover what's new with Docusign IAM or start with eSignature for free
