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/request-a-signature-via-email-using-a-template

My question is, how can I define a web hook URL which can be used to update the envelope's status? I would like to be notified and to be able to update the envelope status in my database once the client signs the documents. Is this possible?

Does EnvelopeDefinition class expose some property which allows me to define the web hook's url?

Dosser

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>[email protected]</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>[email protected]</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>[email protected]</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>

Armament

This is great but I see that it returns some sort of XML. Is there any place where I can see what this XML looks like? It is kind of hard to write a method to process this if I can't see what will be posted to my web hook method... – Dosser

See my amended answer – Armament

@LarryK Link is busted... I've been looking everywhere for this XML schema. – Bangs

@DanBeaulieu I've updated the link and added the WSDL link. – Armament

So, I thought what I was looking for was the XML schema to create a Class object to receive the data. Turns out, what I needed was to extract the envelope information from the HttpRequestMessage. Here's some example code: github.com/docusign/recipe-010-webhook-csharp/blob/master/… – Bangs

Those samples 404 now – Toplofty

@Toplofty -- Thank you for the comment. See updated answer with example XML. – Armament

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

Isogonic

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.

Pleading