The DocuSign Connect interface can send REST API requests to your HTTP listener using HMAC ( hash-based message authentication code ) security. This guarantees the integrity of the contents of the message:
- You generate a secret key in the DocuSign web UI,
- During the webhook call DocuSign generates the SHA-256 hash of the raw body of the message and includes the base-64 encoded value of it in the x-docusign-signature-1 header element,
- Your listener application generates the SHA-256 hash of the raw body of the received message using the same secret key, and compares the result with the value of the x-docusign-signature-1 header element.
To set up HMAC security, first you need to generate a key in the DocuSign Connect web UI. The generated key appears only once in a text box where you cannot highlight the value.
It is important to know, that the secret key is a base-64 encoded text ending with an equal sign (=).
Copy
One way to copy the value is to right-click the field and select Copy. This method does NOT copy the ending equal sign, but you can manually add it to the end of the string.
Inspect
Another way is to right-click the field and select Inspect.
On the Elements tab of the Developer tools double click the key value.
Copy the value.
Make sure to include the equal sign at the end.
Calculating the HMAC hash
When your application calculates the HMAC hash, use the raw body of the message without any transformation, and the copied secret key value, do not decode it from the base-64 format.
Troubleshooting
To inspect the contents of the REST API request use free tools available on the Web.
Use webhook.site to receive test messages from DocuSign. Set the unique URL in your DocuSign application and generate an event by signing an envelope.
The webhook.site UI displays the message including the x-docusign-signature-1 header value and the message body.
To copy the raw content of the body click the Copy link
Copy the raw body of the message and your DocuSign secret key into the Online HMAC Generator and generate the HMAC hash.
Set the
- Key type to TEXT
- SHA variant to SHA-256
- Output type to Base-64
Compare the Result with the x-docusign-signature-1 header value.
