From the Trenches: Handling multiple Connect listeners

For customers who have either multiple platforms or work with multiple integrations, you may find yourself in a situation where you need to use our Connect webhooks system with the intent of routing its notifications to multiple integrations using a single account. The most common result of this is for the customer’s integration to experience writebacks from envelopes not intended for their system. This can lead to a variety of chaos and crossed wires. The good news is, we have a number of options available to you to prevent this scenario.

The issue: 

Docusign Connect is a webhook system that writes back envelope information to your integration based on predefined triggers, such as an envelope switching to a sent or completed status. Connect, by default, is enabled for all users on your account once it has been configured. In terms of restricting who triggers writebacks, we also have a feature named Associated Users that enables you to specify which specific account user can trigger these writebacks. The primary issue becomes sorting out what envelopes are sent to what system, and whether they were intended to go to that system to begin with. We have a number of options available to help with this; the fun part is deciding which one works best for you.

Options:

1. Provision a sub-account

2. Have all listeners active for all users

3. Use Envelope Custom Fields to filter writebacks based on field value

4. Limit writeback via associated users

5. eventNotifications for configuration at the envelope level

Provision a subaccount:

In some cases like this, customers have elected to have our Account Team provision for them what we refer to as a subaccount. Once you have a subaccount, you can move one of these connectors over to that account. That way the envelopes from your primary account automatically write back to one integration, while the envelopes sent through the subaccount only write back to the second integration.

Have all listeners active for all users:

If you’re not using associated users, all users on your account will trigger Connect writebacks by default. Having two connectors running at the same time without associated users will cause all envelopes on this account to write back to all locations. In some cases this is acceptable; in others, make use of envelope custom fields to flag envelopes for one listener or the other.

Use Envelope Custom Fields to filter writebacks based on field value:

In addition to Document Custom Fields, such as Text, SignHere, and Name tabs, we also have a set of custom fields that work at an envelope level. When creating your envelope, you can specify a custom field that either already exists on your account or one fed into this specific envelope. Some of our customers do this already: Salesforce, for example, uses these fields to determine what Salesforce-side object Connect needs to write back to. 

One of the methods you can use is to give a specific custom field value, say "Integration A" in some envelopes vs. "Integration B" in other envelopes. When Connect is configured, you can choose to have these fields included in the writeback. When said writeback occurs, your listener can then check the value of the custom field, processing anything with a custom field labeled "Integration A", while any other envelopes being written back without that custom tab value can be safely discarded. This method requires you have all listeners running on the same account; the tradeoff being that, while everyone on your account can trigger writebacks, you’ll need to implement logic on your side to handle or discard the irrelevant ones.

Associated users:

When using Connect, you can specify a specific list of user IDs that allow writebacks to trigger. When you’re working with multiple listeners one of the ways to restrict writebacks is to use associated users. Let’s say, for example, that you have listener AAA and listener BBB: each are configured within a single Docusign account and both are meant to write back to their independent systems. Using a unique dedicated sender for each listener is an option. If AAA is utilizing their sender with an ID of “123”, you can use associated users to only allow envelopes processed by user ID “123” to write back. You can then use a different user ID, say “567”, for integration BBB, which will achieve the same effect.

This way, only the designated senders for their respective integrations will trigger writebacks, and everyday users can continue to use Docusign.com without having to worry about their work writing back unintentionally to your system.

Event notifications:

Event notifications are a type of Webhook that works on an envelope-by-envelope basis. In the event notification, you will need to include a listener URL along with the events that you want to trigger envelope writeback. For logging and troubleshooting purposes, it’s important to note that the optional parameters loggingEnabled and requireAcknowledgement are not added by default: you will need to supply these parameters in your envelope definitions.

For example: If you wanted to receive a webhook notification only when an envelope is completed, you would include an envelopeEventStatusCode of Completed. Also keep in mind that you can request writebacks based on triggers from individual recipients as well. You can trigger a writeback based on the following events:

• Envelope events: sent, delivered, completed, declined, voided

• Recipient events: sent, delivery failed, delivered, completed, declined, autoresponded

Let’s say that I want a single envelope to write back to my system in the event that an envelope was completed, or a recipient declined, failed authentication, or if their email address triggered a bounceback. I would set requireAcknowledgement to true, loggingEnabled to true, envelopeEvents Completed, and recipientEvents Declined, AuthenticationFailed, and AutoResponded:

{
    "emailSubject": "Please sign the attached document",
    "status": "sent",
    "eventNotification": {
        "url": "https://apps.example.com/app2/webhook-listener",
        "requireAcknowledgment": "true",
        "loggingEnabled": "true",
        "envelopeEvents": [
            {"envelopeEventStatusCode": "Completed",
            "includeDocuments": "false"}
        ],
        "recipientEvents": [
            {"recipientEventStatusCode": "Declined",
            "includeDocuments": "false"},
            {"recipientEventStatusCode": "AuthenticationFailed",
            "includeDocuments": "false"},
            {"recipientEventStatusCode": "AutoResponded",
            "includeDocuments": "false"}
        ],
        "eventData": {
            "version": "restv2.1",
            "format":  "json",
            "includeData": ["custom_fields", "extensions", "folders",
            	"recipients", "powerform", "tabs", "payment_tabs"]
        }
    },
…
…
}

As previously mentioned, the hard part is determining which of these methods will work best for you. If you do have additional questions or would like clarification on any of these details, feel free to open a case on our Support Portal. I or someone from my team would be happy to review potential solutions with you to help make the best decision you can. Alternatively, you can reach out to our Professional Services group to have this implementation developed for you.

Additional resources

• Docusign Developer Center

• @DocuSignAPI on Twitter

• Docusign for Developers on LinkedIn

• Docusign for Developers on YouTube

• Docusign Developer Newsletter