Manually authenticating HMAC signatures for Docusign Connect webhook configurations

•

Summary•3 min read

See how to manually compute and verify HMAC signatures for for Docusign Connect webhook notifications when you're initially setting up your listener.

When configuring a Docusign Connect webhook, HMAC signatures should be used as a security measure to both authenticate the sender (Docusign) and maintain message integrity. Your application should verify the webhook’s notification message as soon as it is received. The Docusign Developer Center includes examples for verifying HMAC signatures in a variety of languages.

This post shows you how to manually compute and verify the HMAC when you’re initially testing your webhook.

To manually verify the notification message’s HMAC signature, you will need the following:

Secret key: This is the key that is assigned by Docusign when you include an HMAC signature in your Connect configuration. Pro tip: it is easiest to use just one HMAC key at a time.
HMAC signature of the webhook request: You can use webhook.site or another public test site to monitor incoming requests and choose one to test its HMAC signature. The signature is the value of the request header “X-Docusign-Signature-1”. Docusign uses Base64 encoding for the signature.
Hashing Algorithm used to generate the signature: This is denoted by the value of the request header “x-authorization-digest”. Note: Current Docusign HMACs use SHA256.
Body of the webhook request: Make sure to turn off any JSON formatting (“pretty-printing”) added by your webhook test site before copying the body.

With JSON formatting:

Without JSON formatting:

Once you have these in hand, manually compute the HMAC signature and check if it matches the signature sent by your webhook:

Use hmac-sha256-online or a similar online HMAC generator that uses SHA256 and the Base64 output format.
Generate the hashed output using your secret key and request body. The HMAC generator must produce a Base64 version of the HMAC:
Compare the output to the HMAC signature in your request header; they should match.

Troubleshooting

If the outputs do not match, perhaps your manually generated output is represented in a different notation than the one given by the request header. HMAC is a binary string, and can be represented in different formats such as binary, octal, hexadecimal, Base64, and others. Docusign’s webhook request represents the HMAC signature in Base64 format. Make sure that your computed output is being represented in the same format before checking to see if they match.

Also check that you used the entire raw version of the HTTP POST request’s body parameter, and check that you copied the body without any added formatting by your test site.

Summary

It’s easy to check the HMAC signature used by Docusign manually. The best security for your server, your webhook listener, is multi-layered. Enable Basic Authentication and HMAC signatures for your webhook configuration: your web server will check the Basic Authentication security. Your application will additionally check the HMAC signature to make sure that the notification message’s sender was Docusign and the message contents were not altered in transit.

Additional resources

Adil BukhariSoftware Developer

Adil Bukhari is a software developer in the Docusign rotational program. He interned with the company in the summer of 2021 and joined Docusign full-time in June 2022. As a part of his first rotation, Adil is working with the Developer Center team to implement new features in Docusign APIs to help developers incorporate Docusign into their apps. He can be reached at adil.bukhari@docusign.com.