Blog
Home/

From the Trenches: Using Docusign Connect with the eSignature SOAP API

Ivan Dinkov
Ivan DinkovSr. Developer Support Advisory Engineer
Summary3 min read

See how to configure Docusign Connect for SOAP and avoid timeout errors caused by improperly configured SOAP responses.

    • Additional resources

    Table of contents

    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:

    DocuSign Connect SOAP setting

    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'?><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/"><body><docusignconnectupdate xmlns="your_namespace"><docusignenvelopeinformation><envelopestatus xmlns="http://www.docusign.net/API/3.0"><envelopeid>your_enveope_id</envelopeid></envelopestatus></docusignenvelopeinformation></docusignconnectupdate></body>
    </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.

    Additional resources

    Ivan Dinkov
    Ivan DinkovSr. Developer Support Advisory Engineer
    More posts from this author

    Related posts

    • Developer Support Articles

      From the Trenches: Testing Docusign Connect with ngrok

      Ivan Dinkov
      Ivan Dinkov
    • From the Trenches: Controlling Sign on Paper options via the API

      Guilherme Flores
      Guilherme Flores

    From the Trenches: Testing Docusign Connect with ngrok

    Ivan Dinkov
    Ivan Dinkov

    From the Trenches: Controlling Sign on Paper options via the API

    Guilherme Flores
    Guilherme Flores

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

    Explore Docusign IAMTry eSignature for Free
    Person smiling while presenting