Using HMAC Security with Docusign Connect
Docusign Connect enables you to secure your Connect listener with HMAC, an industry standard symmetric hashing system. Once HMAC is enabled, special header values will be included in your Connect messages that you can use to verify:
- That the message was sent by Docusign Connect (authenticity).
- That the message contents are exactly the same as they were at the time of sending (integrity).
How it works
When you enable HMAC security with Docusign Connect, you use the Connect screen to define secret HMAC keys. These keys are known only by Docusign and your app, and will be used to sign all Connect messages sent from your Docusign account to your application. For details on how to opt in to use HMAC and define these keys, see How to set up HMAC security with your app.
When using HMAC security, each message sent from your Docusign Connect account includes additional header values, one for each HMAC key you have defined (up to one hundred), which will contain the message body hashed with one of your HMAC keys, using HMAC-SHA256. For example, if you have defined two 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 (only Docusign and your app have access to the secret HMAC keys).
Note: You can use any of your created HMAC header values (Signature-1 or Signature-2, for example) to verify the authenticity of the message.