Skip to main content
Blog
Home/

Introducing HMAC for Partners for Docusign Connect

Author Karan Kaushik
Karan KaushikDeveloper Support Engineer
Summary3 min read

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

      • Additional resources

      Table of contents

      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: 

      1. OAuth authentication

      2. HMAC message signing and authentication

      3. HTTP Basic authentication

      4. Mutual TLS authentication

      5. 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

      Author Karan Kaushik
      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.

      More posts from this author

      Related posts

      • Docusign 2024 Release 3: Capture the Critical Business Value Hidden in Your Agreements
        Intelligent Agreement Management

        Docusign 2024 Release 3: Capture the Critical Business Value Hidden in Your Agreements

      • How to improve your app’s UX while users wait for API calls to complete

        How to improve your app’s UX while users wait for API calls to complete

        Author Larry Kluger
        Larry Kluger
      • Trending Topics: Latest from our forums (November 2024)
        Author Paige Rossi
        Paige Rossi
      How to improve your app’s UX while users wait for API calls to complete

      How to improve your app’s UX while users wait for API calls to complete

      Author Larry Kluger
      Larry Kluger
      Trending Topics: Latest from our forums (November 2024)
      Author Paige Rossi
      Paige Rossi

      Discover what's new with Docusign IAM or start with eSignature for free

      Explore Docusign IAMTry eSignature for Free
      Person smiling while presenting