Introducing HMAC for Partners for Docusign Connect

•

Summary•3 min read

Docusign now lets partners configure HMAC for Docusign Connect on behalf of their customers. See how.

Additional resources

Additional resources

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:

Sequence diagram: HMAC for Partners for Connect workflow

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.

Additional resources

Karan KaushikDeveloper Support Engineer

Karan Kaushik began his Docusign career in January 2022. As a front-line developer support engineer, Karan enjoys working on complex technical problems. He is passionate about using technology to make people's day-to-day lives easier and simpler, leveraging his array of experience across information technology, cloud operations, and software development.