How can I setup a web hook to check on DocuSign Envelope status?

Question

I have the code written which is using envelopes to request a signature from the client like in this tutorial:

https://www.docusign.com/developer-center/recipes/requ

Answer 1

Updated

We now have new series of recommended WebHook code examples which use serverless functions and cloud-based reliable queuing services. These example enable you to receive and process the DocuSign webhook notifications inside your firewall with no changes to your filewall.

Examples are available now for Node. Examples for C#, Java, PHP, and Python are being written.

• AWS listener and worker Node.js examples
• Azure listener and worker Node.js examples
• Google Cloud listener and worker Node.js examples

The format of the webhook XML messages is documented.

Note The Connect guide (March, 2016 date on page 2) is old, and is incorrect in many cases. A new guide is in production. This guide is useful for the XML format information.

WSDL file, including the notification messages format is available.

To see the XML messages that are returned, here's a sample notification for a completed envelope:

<?xml version="1.0" encoding="utf-8"?>
<DocuSignEnvelopeInformation xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.docusign.net/API/3.0">
<EnvelopeStatus>
    <RecipientStatuses>
    <RecipientStatus>
        <Type>Signer</Type>
        <Email>signer_email@example.com</Email>
        <UserName>Signer's name</UserName>
        <RoutingOrder>1</RoutingOrder>
        <Sent>2020-05-23T12:43:07.22</Sent>
        <Delivered>2020-05-23T12:43:14.767</Delivered>
        <Signed>2020-05-23T12:43:18.22</Signed>
        <DeclineReason xsi:nil="true"/>
        <Status>Completed</Status>
        <RecipientIPAddress>141.226.182.70</RecipientIPAddress>
        <ClientUserId>1000</ClientUserId>
        <CustomFields/>
        <TabStatuses>
        <TabStatus>
            <TabType>SignHere</TabType>
            <Status>Signed</Status>
            <XPosition>427</XPosition>
            <YPosition>531</YPosition>
            <TabLabel>Sign Here</TabLabel>
            <TabName>SignHere</TabName>
            <TabValue/>
            <DocumentID>1</DocumentID>
            <PageNumber>1</PageNumber>
        </TabStatus>
        </TabStatuses>
        <AccountStatus>Active</AccountStatus>
        <RecipientId>56e11847-da17-43c3-95f6-d4b675af8621</RecipientId>
    </RecipientStatus>
    </RecipientStatuses>
    <TimeGenerated>2020-05-23T12:43:38.7282968</TimeGenerated>
    <EnvelopeID>cd67ff4a-6cb1-42f3-87d3-f7c149031549</EnvelopeID>
    <Subject>Please sign the attached document</Subject>
    <UserName>Larry Kluger</UserName>
    <Email>larry@worldwidecorp.us</Email>
    <Status>Completed</Status>
    <Created>2020-05-23T12:43:06.753</Created>
    <Sent>2020-05-23T12:43:07.253</Sent>
    <Delivered>2020-05-23T12:43:14.83</Delivered>
    <Signed>2020-05-23T12:43:18.22</Signed>
    <Completed>2020-05-23T12:43:18.22</Completed>
    <ACStatus>Original</ACStatus>
    <ACStatusDate>2020-05-23T12:43:06.753</ACStatusDate>
    <ACHolder>Larry Kluger</ACHolder>
    <ACHolderEmail>larry@worldwidecorp.us</ACHolderEmail>
    <ACHolderLocation>DocuSign</ACHolderLocation>
    <SigningLocation>Online</SigningLocation>
    <SenderIPAddress>208.113.165.37 </SenderIPAddress>
    <EnvelopePDFHash/>
    <CustomFields>
    <CustomField>
        <Name>Team</Name>
        <Show>True</Show>
        <Required>False</Required>
        <Value/>
    </CustomField>
    <CustomField>
        <Name>Office</Name>
        <Show>True</Show>
        <Required>False</Required>
        <Value/>
    </CustomField>
    <CustomField>
        <Name>Order ID</Name>
        <Show>True</Show>
        <Required>False</Required>
        <Value/>
    </CustomField>
    <CustomField>
        <Name>AccountId</Name>
        <Show>false</Show>
        <Required>false</Required>
        <Value>4197223</Value>
        <CustomFieldType>Text</CustomFieldType>
    </CustomField>
    <CustomField>
        <Name>AccountName</Name>
        <Show>false</Show>
        <Required>false</Required>
        <Value>World Wide Corp</Value>
        <CustomFieldType>Text</CustomFieldType>
    </CustomField>
    <CustomField>
        <Name>AccountSite</Name>
        <Show>false</Show>
        <Required>false</Required>
        <Value>demo</Value>
        <CustomFieldType>Text</CustomFieldType>
    </CustomField>
    </CustomFields>
    <AutoNavigation>true</AutoNavigation>
    <EnvelopeIdStamping>true</EnvelopeIdStamping>
    <AuthoritativeCopy>false</AuthoritativeCopy>
    <DocumentStatuses>
    <DocumentStatus>
        <ID>1</ID>
        <Name>Example document</Name>
        <TemplateName/>
        <Sequence>1</Sequence>
    </DocumentStatus>
    </DocumentStatuses>
</EnvelopeStatus>
<TimeZone>Pacific Standard Time</TimeZone>
<TimeZoneOffset>-7</TimeZoneOffset>
</DocuSignEnvelopeInformation>

Answer 2

There are two possible ways to do this.

One is to set up an account wide Connect Configuration within the DS WebApp, this will send the requested event notifications on every envelope sent/completed to the URL: https://www.docusign.com.au/sites/default/files/connect-guide_0.pdf#page=5

You can also define this per envelope with the eventNotification parameter. However, the parameter is not baked into the provided recipes. EDIT: I stand corrected, see Larry's response below https://www.docusign.com.au/p/RESTAPIGuide/Content/REST%20API%20References/Send%20an%20Envelope.htm

Answer 3

Another way to test your "Listener" is to get the DocuSign XML response using

https://webhook.site

From there you will see the POST request with the complete XML body for your envelope.

TEST THE CREATE ENVELOPE FIRST

Before I would test my Listener, I wanted to confirm that my C# code would trigger the WebHook (via EnvelopeDefinition.EventNotification) in the DocuSign Envelope.

EnvelopeDefinition.EventNotification sets 2 lists of objects for EnvelopeEvent & RecipientEvents. Properly configuring these will fire the trigger in DocuSign Connect (Webhook).

All that was needed was to set the EventNotification.Url = the custom URL created for me on https://webhook.site

I locally ran my C# API code to create a DocuSign Envelope that would trigger the Webhook. Then I used the the DocuSign email (received moments after creating the envelope) to sign the document - which again fired the Webhook to my test listener.

GET THE XML My properly configured code fired the DocuSign Connect (Webhook) POST event. I can see the POST request (and its XML body) on my custom URL at https://webhook.site

RESEND THE XML Finally, copy the POST request XML sent from DocuSign and paste that XML in PostMan. Then I can locally use PostMan to "resend" that POST request (and XML body) to test my local Listener API that I am developing.