How to Secure Your DocuSign Webhook Listener
By: Thiwanka Wickramage
Tags: Docusign Tutorial, Esignatures, Security, Docusign, Webhooks

It is necessary and recommended for most developers to secure their webhook listener. This can prevent spam, and also protect your application in case bad actors attempt to send fake data to trigger your own application’s workflows.

DocuSign provides several options for securing your webhook listener. For Account-level Connect configurations, the recommendation is to use HMAC.

In this article we going to talk about all other securing options and walk you through the HMAC implementation.

Basic Authentication Header

This is the most simple and straightforward way to authenticate your data that comes from the DocuSign and verify webhook URL. We can easily enable this option from the DocuSign console and you need to provide an username and a password.

When you enable this this method to secure your endpoint, DocuSign will include the Authorization header in its every request and send it to your web server.

Access control and Basic Authentication requirements are need to be implemented by your web server using the Authorization details.

As per the DocuSign documentation, this method is also the one with the greatest attack surface, as the username/password combination is sent in the headers on every request. They recommend combining this method with HMAC whenever possible, unless you are getting started or your services requires no sensitive data.

Mutual TLS

Mutual TLS (mTLS) authentication ensures that traffic is both secure and trusted in both directions between DocuSign and your webhook listener. This implementation is can be little difficult to configure on your web server. So I will skip this part for now, I hope to write another detail article about the mTLS implementation.

HMAC

HMAC is the most common Webhook security mechanism. This method can very easily configure on the DocuSign and easily implement the validation on your client side. On the DocuSign’s side we need to generate a key, that key we need to securely store in your application. Once the key is generated it will not be shown again from DocuSign.

Add HMAC keys for your app

Log in to your DocuSign account in either the sandbox or production environment. From the top menu, select Admin/Settings. Select Connect in the INTEGRATIONS section in the left menu. You need have an existing custom Connect configuration or create a new one. Go to the Connect Keys from the right side menu.

6. Now you can able to add a secret key. Save that key in a secure location that key will not be shown again. Following image I have already created 2 keys and key 3 is the newly created key.

Now you have successfully generated a key. Now you have to map that key with your DocuSign Connect APIs.

As I mention in the step 4, you need to have a custom Connect configuration. Go to your Custom Configuration Settings by opening the Connect configuration and you can find the Integration and Security Settings section at the bottom.

When you enabled the HMAC Signature in the settings, it will select all the keys that you have created. After you save the settings, you have successfully configured the HMAC signature for your Connect requests.