From the Trenches: Using DocuSign Connect with the eSignature SOAP API
DocuSign Connect is a popular service among DocuSign clients because it provides write-back functionality, which means your application can be notified whenever the state of an envelope or a recipient changes. For the notifications, customers can choose between JSON and XML data formats.
When using XML as the response type, customers can have notifications formatted as SOAP client requests to their SOAP listener. The option is available in every legacy (XML) custom configuration, under Settings > Connect:
Things might get a little difficult when it comes to setting and using SOAP. According to the DocuSign Connect SOAP Interface guide, there are four requirements for implementing SOAP listeners, the last of which is the most overlooked:
Return the EnvelopeID passed to it, if received. Otherwise, it should return a SOAP Fault.
The most important thing to remember is that, because this is a SOAP service, the response body must always be properly formatted SOAP XML and include the EnvelopeID. This should be the case, even when responding with a “200 OK” message. Failure to do so will result in an “Operation timed out” error.
As a result, after a certain amount of time, the notification service will, if so configured, retry the request multiple times before stopping the retry process. When this is combined with notifications for newly created envelopes, your listener will then be overloaded, and the DocuSign service will be overburdened.
Unfortunately, many customers are unaware of the error for a long time because their listener only receives partial envelope status notifications. They don't get recent status updates, or none at all, because the service tries to resend old "undelivered" messages and eventually stops after a few failed attempts.
Troubleshooting this problem can be time-consuming and difficult. As a developer, you may spend a lot of time tracing calls and examining server and Connect logs because the error sounds like a network issue rather than a coding issue.
Your XML response body should look like the example below:
<?xml version='1.0' encoding='UTF-8'?>
<soap:Envelope xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/08/addressing' xmlns:wsse='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd' xmlns:wsu='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd' xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'>
<soap:Body>
<DocuSignConnectUpdate xmlns='your_namespace'>
<DocuSignEnvelopeInformation>
<EnvelopeStatus xmlns='http://www.docusign.net/API/3.0'>
<EnvelopeID>your_enveope_id</EnvelopeID>
</EnvelopeStatus>
</DocuSignEnvelopeInformation>
</DocuSignConnectUpdate>
</soap:Body>
</soap:Envelope>
Before deploying your app to production, it's a good idea to test your Connect configuration and check for errors. One way is by going to Settings > Connect > Failures in your DocuSign web app. The results are sorted by the most recent one. Alternatively, the eSignature API contains an API call, ConnectEvents:listFailures, that can filter for Connect errors for a specified date range.
By making sure you include the EnvelopeID in your XML response body, you can prevent this error and avoid Connect timeouts in your SOAP apps.
