How to Secure Your DocuSign Webhook Listener

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

1. Log in to your DocuSign account in either the sandbox or production environment.
2. From the top menu, select Admin/Settings.
3. Select Connect in the INTEGRATIONS section in the left menu.
4. You need have an existing custom Connect configuration or create a new one.
5. 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.

What really happen here is DocuSign will generate a HMAC hash code from the request event payload and key. This key is that we generated in the above section. Each request that sent from the DocuSign Connect to your application, it will include the additional header values.

Let’s say you have defined two Connect Keys, then two headers, X-DocuSign-Signature-1 and X-DocuSign-Signature-2, will be added. They will contain the message body hashed with your first and second secret keys, respectively.

After receiving the message containing the HMAC header values, your app must validate that they are authentic by re-creating them. If the message body (including line ends) hashed with one of the HMAC keys matches one of the provided HMAC header values, you can verify that the message came from DocuSign and payload is not tampered.

Validate a webhook message using HMAC

You have completed all the configuration part from the DocuSign’s side. Now you have to implement the webhook connection authentication part from your application.

As I mentioned earlier, when your app receives a message from DocuSign Connect, this message will contain headers with the data hashed with the application’s defined HMAC keys, as shown below.

[X-DocuSign-Signature-1, DfV+OtRSnsuy.....NLXUyTfY=]
[X-DocuSign-Signature-2, CL9zR6MI/yUa.....O09tpBhk=]

After receiving the message, your app should verify the HMAC signature by re-creating one or both of the signatures by hashing the raw message body with one or both of the app’s HMAC keys.

I use NodeJS to show you how to implement this validation and also it’s very straightforward process to implement with the other languages. I wrap the webhook validation process in a single function that will throw an error when the validation failed.

yeah I know it’s a simple piece of code 😉. I will explain the code line by line.

In the Line no 3 and 4, I extract signature values from the header and push to the array.

In the Line no 7, we need to provide a key (DOCUSIGN_SECRET_KEY) that you have generated and securely stored in your application.

In the line no 8, we need provide full event body to generate the HMAC hash code with the key.

In the line no 10, computation will return the HMAC hash code that generated from the event body and the given key.

At least one of the computed digests must exactly match its corresponding header value. If there is no match, then the event payload may be compromised and it should not be trusted. Only one match is required.

As I said it’s very simple and straightforward implementation. This is how I validate DocuSign Connect APIs in my application. Feel free to give me any suggestions to improve the implementation, any questions or anything I have done wrong.

If you liked this post, don’t forget to share and follow. Until next article, happy coding.!

🤝 Please Read My Other Articles

👉🏻 DocuSign Connect with AWS S3 -Part One
👉🏻 DocuSign Connect with AWS S3 -Part Two
👉🏻 My Serverless deployment process Experience
👉🏻 Configure AWS Route 53, CloudFront and SSL Certificate