Recipient Connect
Recipient Connect is a new feature for the DocuSign Agreement Cloud. It provides webhook notifications whenever a user in your DocuSign eSignature account is a recipient of an envelope and a specific envelope trigger event occurs. Your application can be notified for envelope complete and other events; the complete list is below.
The current Connect webhook features at the account and envelope level can only be used by the sender and sending account of the envelope. With Recipient Connect, your software application does not need any association with or permissions from the sender of the envelope.
Use cases
Use cases include archiving of received documents, initiating business processes, and more. As more and more organizations both send and receive eSignature documents, Recipient Connect enables more automation to eliminate manual processes.
Requirements
To use Recipient Connect, your account (whose users receive the envelopes) must be provisioned and set up as follows:
Make sure Recipient Connect is provisioned
Recipient Connect needs to be provisioned for your account. To see if it is, open the eSignature Administration app (via the Settings link at the top of the DocuSign web app). Navigate to the Integrations/Connect screen. Click the Add Configuration drop-down item. If the Custom Recipient item is available, then Recipient Connect has been provisioned for your account.
Recipient Connect is available now via its Early Access Program. Use this form to request access.
General availability (GA) of Recipient Connect will be announced via DocuSign’s Product Release notes. Once the feature is generally available: for production accounts, if you don’t see the Connect screen, or if the Custom Recipient configuration type is not included, then discuss your needs with your DocuSign account manager.
After GA, current and new developer accounts on the demo platform will be provisioned with Recipient Connect.
Claim a domain via Access Management with SSO
Recipient Connect also requires a DocuSign organization and the Access Management with SSO feature. You do not need to use SSO, but the account or accounts that will receive envelopes and trigger Recipient Connect must be associated with an organization, and the organization must have claimed one or more domains.
For production accounts, if you don’t have the Access Management with SSO feature, contact your DocuSign account manager. For developer accounts, submit a Developer Support case and include your developer account number.
The claimed domain admin guide provides information on how to claim your users’ email domain or domains for the organization your account is associated with. You will also need to associate your account with an organization.
Recipient Connect qualified recipients and triggers
Qualified recipients are the envelope recipients whose primary account is the account that has a Recipient Connect configuration, and the account belongs to an organization that has claimed the recipient’s email domain. Only qualified recipients can trigger a Recipient Connect notification, but there are additional factors: did the sender of the envelope require the recipient to pass an authentication step and is the Recipient Connect configuration set to include or not include the envelope documents in the notifications?
Event Trigger descriptions
- Envelope Completed trigger event. The envelope has been completed, all relevant signers have signed, cc recipients have been notified, etc.
- Recipient Sent trigger event. The envelope’s qualified recipient has become a current recipient for the envelope.
- Recipient Delivered trigger event. The envelope’s qualified recipient has opened the envelope.
- Recipient Signed/Completed trigger event. The envelope’s qualified recipient has signed or otherwise completed the envelope. For example, if the qualified recipient is a cc recipient, then the envelope has been sent to the recipient.
- Recipient Delivery Failed trigger event. The envelope’s qualified recipient is a current recipient for the envelope, and DocuSign attempted to email the recipient. But DocuSign received a negative acknowledgement for the email’s delivery.
- Recipient Declined trigger event. The envelope’s qualified recipient has declined to sign the envelope.
Notification delivery
Depending on whether the recipient has passed a required authentication step or not, and whether the Recipient Connect configuration includes documents or not, affects whether the notification will be sent or not:
The qualified recipient does not have an authentication requirement: the notifications will be sent as described above.
The qualified recipient has not yet passed a required authentication step, and the Recipient Connect configuration does not include the envelope documents: For the early access program, a notification is sent. For GA, a more limited notification may be sent.
The qualified recipient has not yet passed a required authentication step, and the Recipient Connect configuration does include the envelope documents: For the early access program, no notifications are sent. For GA, a limited notification that does not include the envelope documents will be sent.
The qualified recipient has passed a required authentication step: Once the recipient has passed the authentication step, any subsequent event triggers in the configuration will cause a notification to be sent. For example, the Recipient Delivered event.
Notification queuing
Recipient Connect notifications are queued and sent using Connect’s aggregate queuing model. This means that multiple notifications for a specific envelope that occur at almost the same time will usually cause only one notification to be sent. For example, suppose you’ve selected both the Envelope Completed and Recipient Signed/Completed trigger events. For many envelopes, those events occur almost simultaneously. For most of these cases, only one notification message will be sent, for the later event (Envelope Completed.)
Known issues
- For the early access program, when a notification is not sent because the qualified recipient has not yet passed their required authentication step and the configuration includes the envelope’s documents, an error item is added to the Recipient Connect log. These error messages will not be created after GA. This is tracked as internal issue CONNECT-2458.
- As discussed above, the notification messages sent when the qualified recipient has not yet passed their authentication step have not yet been finalized.
- The notification flow for the trigger Recipient Authentication Failure is still being finalized.
See the (future) GA announcement for an update on these issues.
Create a Recipient Connect configuration
Create your first Recipient Connect configuration by using the eSignature Administration app available via the Settings link at the top of the DocuSign web app. Choose the Custom Recipient option and fill in the resulting Custom Recipient Configuration Settings form:
- Name: the name of the configuration.
- URL to publish: an HTTPS URL is required. This is the URL of your server, your listener. For testing, you can use a free internet webhook service. Here’s a Google list. See below for software architecture recommendations.
- Recommendation: check the Enable Log and Require Acknowledgement checkboxes.
- Use the Include Data checkboxes to determine which data will be sent in the notification messages. Recommendation: Do not include documents, because they make the POST messages to your listener server very large. Since Base64 encoding is used, the document data will be 25% larger than the documents’ actual sizes. To create a more robust and reliable integration, DocuSign recommends that your listener application use the eSignature API to retrieve envelope documents when needed.
- Associated Users: Use these parts of the form to determine whether your application should be notified when any qualified user in the account, or just selected qualified users, should trigger a Recipient Connect notification message. Remember that only qualified users who have selected the account as their primary account and whose email addresses are in the account organization’s claimed domains can trigger a notification. While all of the users in an account are listed in the Available/Selected users list during the early access program, only those in a claimed domain can actually trigger a Recipient Connect notification message. Currently, the Available/Selected users lists all of the account’s users. But only the users in the account who have an email address with a claimed domain will have an effect if selected, and only they should be listed. In a future release, only the users in a claimed domain will be listed. This issue is tracked by DocuSign via internal ticket CONNECT-2305.
- Check the event or events that should trigger a notification message.
- Recommendation: Check the Include HMAC option and configure an HMAC secret. The HMAC signature sent with the notification messages provides your application with verifiable guarantees that the message author was DocuSign and that the message was not modified since it was sent. Your listener application verifies the HMAC. See the documentation.
- Recommendation: Also check and set up the Include Basic Authentication Header option. Basic Authentication can be implemented as a configuration option for your web server. It will stop random doorknob jigglers from reaching your listener software.
Then click the Add button and you’re ready to test!
Software architecture recommendations
To reliably receive and process Recipient Connect notifications:
- Your server (your listener) should be available 24 hours a day, every day of the year, with no scheduled maintenance times.
- Your listener should be reliable with an uptime goal of 99.99% or better.
- Your listener should not process notifications synchronously, instead, it should process them asynchronously by adding new notifications to a reliable queue and then acknowledging receipt of the notification back to DocuSign. Simultaneously, a different software process (the worker) should handle each notification message appropriately.
- Your listener must be available as a URL on the public internet so DocuSign’s servers can communicate with it. If your servers are behind your firewall then the firewall must be modified to enable DocuSign to communicate with your server.
The above requirements can be difficult and expensive to implement correctly and securely.
Fortunately, a secure, reliable alternative configuration is available and works well at a very low cost:
- Instead of creating your own listener with its requirements of modifying your firewall, create a small program on AWS, Azure, Google Cloud, or similar. That program will add the incoming notification messages to a secure queuing service that is also hosted in the cloud.
- Behind your unmodified corporate firewall, your application can use an SDK for the cloud queuing service to retrieve the notification messages as soon as they arrive.
- This configuration does not require any corporate firewall changes, since the communications to the queuing service are all outbound from your application server.
- Code examples available from DocuSign for AWS, Azure, and Google Cloud. And the cost is less than $10 per month for a million notifications a month.
- This configuration does require the use of a cloud service, and requires that documents be retrieved from DocuSign as needed, instead of including them in the notification messages.
- More information: blog post, videos for Azure, Google Cloud, and code examples for AWS, Azure, and Google Cloud.
Testing your Recipient Connect configuration
- You will need two DocuSign accounts that are not associated with each other: that is, they do not belong to the same DocuSign organization and do not use the same email addresses. You can use two different developer accounts to get started.
- As described above, the recipient’s DocuSign account must belong to a DocuSign organization, and that organization must claim the email domain used by the recipient. Both a developer account and a production account can claim the same domain name.
- Create a free account on a webhook test website.
- Create a Recipient Connect configuration in the recipient’s account, using your personalized URL from the webhook website.
- Using the sender DocuSign account, send an envelope to the recipient. The recipient can be a signer in the envelope, a cc recipient, or another type of recipient.
- A couple of minutes after the trigger event has occurred, you should see the incoming notification message in the webhook website.
Summary
Recipient Connect provides additional powerful functionality for automatically processing DocuSign envelopes. Recipient Connect has many use cases and we look forward to hearing about your experience with the feature. Recipient Connect is available now under the early access program.
