Skip to main content

Generating HMAC Keys for DocuSign Integration with Zengine

Thomas Hardy
  • Updated

This article is meant to be used with the article Setting Up the DocuSign E-Signatures Plugin.  

Note that this article describes a process and uses images from DocuSign that are accurate at the time of publication.

 

Contents

 

Overview

The DocuSign E-signatures plugin integrates DocuSign together with a normal Zengine workspace to add an electronic signature (e-signature) process to any program workflow. This plugin integrates a DocuSign account with a specific workspace. In order for Zengine and DocuSign to securely interact with each other, a security feature called an HMAC Key must be generated in a user’s DocuSign account and validated in the Zengine workspace to be connected.

This article covers the process of generating an HMAC Key in DocuSign and entering it into a Zengine workspace to connect the two platforms.

 

The Purpose of HMAC Keys with the DocuSign E-Signatures Plugin

An HMAC (Hash-based Message Authentication Code) Key is a type of security code used in various applications to ensure the data integrity and authenticity of a message. When a different application connects to DocuSign via an API (as Zengine does using a DocuSign E-signatures Plugin configuration), DocuSign uses an HMAC Key, associated with a user’s DocuSign account, to ensure that the document package - or “envelope” - sent to various recipients for electronic signature has not been tampered with. In order to work correctly, that HMAC Key must be shared with a Zengine workspace to enable secure communication between the two platforms.

DocuSign restricts the ability to generate HMAC Keys to users with a Business Pro or higher-level account; as a result, this is necessary to use the DocuSign E-signatures Plugin in Zengine. 

 

—IMPORTANT—

If you do not have a Business Pro or Enhanced Plan with DocuSign, you will need to upgrade before generating an HMAC Key for DocuSign integration.

 

Generating HMAC Keys in a DocuSign Account

Once a DocuSign account has been upgraded to the appropriate plan, HMAC Keys can be generated within the settings of a user’s or organization’s DocuSign account.

  1. Begin by accessing DocuSign and logging into the appropriate account.
  2. Select Settings on the white bar at the top of the page. (Note: the Settings option will not be visible if the DocuSign account not a Business Pro or similar-level plan.)

  1. A Settings landing page will display, with options to Find a Setting or User, a Notifications pane, a link to Admin Resources, and so forth. A gray pane labeled Overview will be present on the left side of the screen. 

  1. Scroll down and identify the section heading labeled INTEGRATIONS.
  2. Select Connect under INTEGRATIONS.

  1. The main page will change to display Connect at the top with a menu bar just below it showing several options. Select Connect Keys.

  1. Any existing connection keys (synonymous with HMAC Keys) will be displayed on this page; the image below shows four previously generated keys, but this will vary. To generate a new HMAC Key, select the blue button labeled Add Secret Key at the bottom of the page.

  1. A new row will appear at the bottom of the list of keys onscreen showing the long multi-character code. This is the new HMAC Key. Select the Copy to Clipboard button on the right side of the text box containing the key to copy it.

  1. Either paste the key in a secure document or location for storage, or - with the HMAC key still copied to the clipboard - proceed to the next section Using an HMAC Key with the DocuSign E-Signatures Plugin immediately.

 

—IMPORTANT—

The full content of each secret key is only visible directly after creation. For security reasons, only the first four characters of the key display in the eSignature Settings UI on subsequent views, and it cannot be copied after a user leaves this page. Be sure to record the key as soon as it is created and store its value securely. 

 

Using an HMAC Key with the DocuSign E-Signatures Plugin

Before continuing, be sure that the DocuSign E-signatures Plugin has been installed in the workspace and at least one configuration has been set up. For more information, see the article Setting Up the DocuSign E-signatures Plugin.

Once at least one configuration has been enabled, a new section will appear on the configuration settings page (below the configuration tiles) with the heading Webhooks Settings (Docusign Connect API - HMAC Keys).

 

 

This is where an administrator should enter in an HMAC Key that has been generated in a user’s DocuSign account. A configuration cannot function without at least one correct HMAC Key.

To enter and confirm an HMAC Key:

  1. Once the HMAC Key has been generated in a user’s DocuSign account, copy and paste the full key into one of the configuration fields labeled HMAC Key #[X]. ([X] will be replaced with 1, 2, 3, etc. as appropriate.)
    • Only one HMAC Key is needed, but additional keys can be added if an HMAC Key becomes obsolete, no longer functions, or needs to be changed.
  2. When the HMAC Key has been added to one of these configuration fields, press Enter. A message will appear on screen informing the user that a Test Envelope will be sent to confirm the HMAC Key associated with the user’s DocuSign account. Select Yes to continue or Close to cancel.

  1. The HMAC Key entry will change to display Saved and the icon to the right of the configuration field will show a yellow exclamation mark; hovering over this icon will show that the HMAC Key is in the process of being confirmed. 

  1. The owner of the DocuSign account may receive email notifications from DocuSign informing them that they’ve received an envelope to sign, and a few moments later, that the envelope has been voided. No actions need to be taken with respect to these emails.
  2. The process of confirming an HMAC Key may take a few minutes. Once the key has been confirmed, the HMAC Key configuration field will display Confirmed and the icon will change to show a green checkmark.

If an incorrect HMAC Key has been pasted, or an HMAC Key was generated from a different DocuSign account than the one used to enable the DocuSign E-signatures plugin configuration in Zengine, this field will display Invalid and the icon will change to show a red X. 

If this occurs, delete the value in this field and paste the correct HMAC Key, or disable and re-enable the configuration; this should prompt the user to enter in their DocuSign account login credentials again, and the credentials for the correct account should be entered.

Note that the same HMAC Key can be used for multiple configurations within a workspace, or across multiple workspaces; the HMAC Key is unique to a user’s DocuSign account rather than a configuration or Zengine workspace. In other words, the HMAC Key only needs to be entered once, unless there are specific reasons to enter additional HMAC Keys (such as one has been cycled out and is no longer in use).

Return to Contents


What did you think of this article? If you found this article helpful, let us know below! If you have suggestions for how to improve this article, please leave a comment. Your feedback helps us improve the experience for others.

Related articles

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk