How to get completed envelope with web hooks

Question

I want to use the DocuSign web hook so that I can store completed envelopes in our internal document repository system. I've read that the preferred approach to getting the documents is to use the envelopeId returned in the incoming web hook message and use the API to query for the envelope and its contents in order to keep the incoming message light and not have to deal with any large file issues.

With this approach, I need to authenticate my service account in order to query for the envelope. Since I want to do this as a backend process, I'm not sure how to authenticate since it appears that with all the authentication approaches, user interaction is needed to permit the app to access DocuSign.

What am I missing? What is the best option to accomplish this? Should I just include the contents of the envelope in the incoming message so that I don't need to make another call to retrieve it?

Answer 1

Ok, so I finally got this all working. Everything that Payf1, Amit, and Larry mention is correct and has good references to pieces of this puzzle. Here are the steps I took to setup JWT to use the DocuSign API without getting user consent (called Admin Consent for Internal Apps. There is a whole document on this).

1. In the Admin portal, add your app (Integrations > Api/Keys > Add App/Key). Once it's saved, click Edit and create an RSA key pair. Copy the text from the private key and add this to a text file in your application.
2. Enable "Organization Administration" on your account by contacting your DocuSign account manager (there might be a cost with this).
3. Log into your account, go to the Organization Administration > Applications. Authorize your application with permissions "impersonation signature".
4. Still in Organization Administration, click Domain > Claim Domain. Enter your domain and follow the instructions to add to your DNS using this document
5. Once the domain is fully setup and verified, in Organization Administration, go to Users. Find the user or service account that you want to impersonate. Click their name to open their profile. Click Applications > Authorize Applications > Select your app. Enter the permissions "impersonation signature".

6. In your app, use this code to get the authorization token. The User_id is the guid for the user you granted access to in Step 5 (found in their profile page).

   byte[] privateKeyBytes = System.Text.Encoding.UTF8.GetBytes(File.ReadAllText(privateKeyFullPath));

   List<string> scope = new List<string>();
   scope.Add(OAuth.Scope_SIGNATURE);
   scope.Add(OAuth.Scope_IMPERSONATION);
   
   OAuthToken _AccessToken = _ApiClient.RequestJWTUserToken(client_id, user_id, OAuth.Demo_OAuth_BasePath, privateKeyBytes, 4, scope);
   

For my app, I'm just wanting to return the envelope when I receive the envelope ID from the DocuSign web hook:

_ApiClient.Configuration.AddDefaultHeader("Authorization", "Bearer " + _AccessToken.access_token);
EnvelopesApi envelopesApi = new EnvelopesApi(_ApiClient.Configuration);
EnvelopeDocumentsResult docList = envelopesApi.ListDocuments(accountId, envelopeId);

Answer 2

Sorry for the confusion. I’m specifically asking about the JWT authentication. What I’d like to do is only receive the envelope ID from the incoming web hook call. Then use the DocuSign API to query for the signed documents.

When using this approach with JWT, my understanding is that I need to get an “access code”. I think I’ve found one missing piece to the puzzle in that I needed to enable Organization Administration in my account. I’ve done that and authorized my app with the “admin content scope” to “extended”. I want to process the signed document with a backend process. My understanding to get the access code is that I need to make this request via a browser. But there isn’t a browser for a user to interact with. So this is where I’m getting stuck. How do I get the access code and/or an access token for a back end process in order to make this API call?

Answer 3

You are mixing two things, one is Webhook which does not need JWT AccessToken, as it is just a POST service call to your listener from DocuSign as soon as your subscribed trigger events happen in an envelope lifecycle. You need JWT generated AccessToken for calling any DS API service. Obtaining Consent will explain how to get consent for generating AccessToken using JWT. If all your users in DS Account as with same corporate email, and you can claim that corporate email domain in DS by updating a TXT token in that corporate email DNS then you can use Admin Consent. Also for using Admin Consent, you need to check with your DS Account Manager if your subscription plans allow you to use Organization feature in DS or not. But if you do not proper subscription plan or you cannot claim email domain in DocuSign then you need to explicitly get the User consent before generating an Access Token for that user.

Answer 4

Your question is excellent. I agree with @Payf1's answer. Here's some additional info.

Subscribing your webhook

You need to have a subscription to the DocuSign webhook system so your listener will receive the webhook notifications.

Option 1: Set up the Connect system at the account level. This will give you a subscription for every envelope sent by any user on the account, for envelopes sent via Powerforms, via the DocuSign web tool, and via the API. Just ignore incoming notifications for the envelopes you're not interested in. Don't reject them, acknowledge and then ignore them.

Option 2: For each envelope that you want a webhook subscription for, you must both create the envelope using the API and include the eventNotification object in the Envelopes::create call.

The incoming notifications are the same for either option.

Listening for and acting on the webhook notifications

To properly handle the incoming stream of webhook notifications, the best architecture is to place each notification on a reliable queue, then acknowledge the message receipt to DocuSign.

Reliable queues are offered by Azure Service Bus, AWS Simple Queue Service, Google Cloud Tasks, and by many on-premises software queuing libraries.

Then, separate worker processes can process the messages asynchronously.

As you correctly said, the pro-tip recommendation is to not include the documents in the notification bodies.

So the worker processes need a DocuSign access token to make the API calls to DocuSign to retrieve the envelopes' documents. As @Payf1 suggested, the JWT Grant is often the right authentication solution. Auth Code Grant authentication grant can also be used if your app uses the refresh token to generate an access token as needed.

Examples

For JWT Grant, see the eg-01 series of code examples.

Answer 5

Welcome to the community Scott.

You can either use a separate API call to retrieve the document or you can choose to include the document PDFs and/or Certificate of Completion in your webhook. Webhook logs will always include the entire envelope data including field values as well. Please see here for more info.

To answer your question related to authentication, you need to use a service integration that integrates directly with a DocuSign account and does not authenticate every end user. In other words, a user-less integration that authenticates your document repository system and DocuSign. JSON Web Token Bearer Grant is the authentication method you might want to look into. Please see here for more info.