docusignapidocusignconnect

Is Connect Configuration required for setting up HMAC in envelope-level webhook in DocuSign


I want to use Envelope-level webhook with HMAC Security for notification, I found in the eventNotification object, a field 'includeHMAC' and for using this I need to setup a HMAC keys in connect page. I have generated a new key, but in the doc https://developers.docusign.com/platform/webhooks/connect/setting-up-hmac/ there are steps which asks to include the HMAC signature in connect configuration, I understand this is required if I want to use account-level webhook, for envelope level webhook do I need to create a custom configuration for HMAC security, or generating the key itself is enough?


Solution

  • Yes, HMAC codes (signatures) can be included for envelope-level connect webhooks.

    To do so, set the includeHMAC attribute to true in the eventNotification object of the Envelopes:create API call. See the docs

    However, you need to set up the HMAC keys (secrets) using the Connect section of the eSignature Admin tool. So that means that the account needs to have the Connect feature enabled.

    You do not need to set up an account-level Connect configuration.

    We have an internal enhancement request CONNECT-2406 to enable the HMAC secrets screen to be available to all customers. Please ask your DocuSign contacts to add your information to that ticket.

    Recommended: you can also raise this as an issue via https://feedback.docusign.com

    HMAC alternative

    The main alternative to using HMAC to authenticate the webhook notification message is to use Mutual TLS.

    Also

    The OP asks:

    Is it possible to enable this via esignature api for every account that uses my integration (app created from the Apps & Keys) and generate the HMAC keys programmatically.

    Unfortunately the API for managing HMAC keys is not public. But you can add your vote to change this! See this DocuSign feedback item