Introducing HMAC for Partners for DocuSign Connect
DocuSign offers five different mechanisms to authenticate DocuSign Connect event messages; that is, to make sure that messages are coming only from DocuSign and not from someone else:
- OAuth authentication
- HMAC message signing and authentication
- HTTP Basic authentication
- Mutual TLS authentication
- Digital signature (SOAP only, deprecated)
DocuSign Connect enables you to secure your Connect listener with hash-based message authentication code (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).
To learn how to set up an HMAC key on your account, see Using HMAC Security with DocuSign Connect on the DocuSign Developer Center.. For guidance and examples on how you can verify the HMAC key, see How to validate an HMAC signature.
We are excited to announce a new addition to HMAC for DocuSign Connect. This feature lets partners and integrators use their HMAC keys for their clients’ event messages. This will enable integrators and partners to manage Connect security for their clients in a more streamlined way. Here’s how the authentication flow for this new Connect security option works:
An HMAC key must be set up for the account where the integration key is located. This would be the partner’s or integrator’s account. You can then set the integratorManaged parameter to true while creating the Connect configuration on the client’s account. Connect will then use the partner’s or integrator’s HMAC key/s while sending event notifications. You can use this parameter for account-level and envelope-level configurations.
This functionality is only supported in the API. It is currently available in demo and will be available in all production environments by the end of March.
A sample payload for what the integratorManaged parameter looks like is below:
{
"configurationType": "custom",
"urlToPublishTo":"Your Webhook URL",
"allUsers": "true",
"name": "Your configuration name",
"allowEnvelopePublish": "true",
"enableLog": "true",
"includeHMAC": "true",
"integratorManaged": "true",
"deliveryMode": "SIM",
"events": [
"envelope-completed"
],
"eventData": {
"version": "restv2.1",
"includeData": [
"tabs",
"payment_tabs",
"custom_fields",
"powerform",
"recipients",
"folders",
"extensions",
"attachments",
"prefill_tabs",
"document_fields"
]
},
"requiresAcknowledgement": "true"
}
We recommend testing this out in your demo account to ensure everything works as expected.