Event Notifications using JSON SIM and HMAC

Jonathan SammonsDeveloper Support Engineer

•

Summary•5 min read

An overview and example of using envelope level event notifications for obtaining envelope information as they progress with the JSON SIM format and HMAC security.

I’ve recently noticed some developers trying to use envelope-level Connect event notifications over account-level event notifications. Envelope-level event notifications give you more control over when these events are sent to your listener and how they’re triggered, but can be a bit more cumbersome to set up initially.

While some of these functionalities are quite straightforward to configure when you create a configuration on your Docusign account for the account-level event notifications, some developers have been left scratching their heads as to how this needs to be specified on their envelope for envelope-level event notifications. In the example that I will share below, I’m going to specify that the event notification is sending the event details in JSON format with each message sent, as opposed to aggregate messages. I will also be including HMAC in my call as an example of how you can use your HMAC key for a customer account without them needing to create a HMAC key themself. Before we jump to the code example, I think it’s important to understand a bit more about the JSON SIM format and using HMAC on your Connect events.

JSON SIM format

Docusign Connect has been a feature available for many years to track envelope information and the status of your envelopes soon after they have been updated. The JSON SIM format builds on this by focusing on the events of the envelope, rather than the current status of the envelope itself. By focusing just on the event updates of the envelope, the JSON SIM format allows you to get smaller messages to your listener and event updates in real time. It also offers more ways to track what is happening with your envelopes by tracking specific events that happen on them.

HMAC Security with Docusign Connect

HMAC is an encryption method using SHA256 that helps you know that the message that you receive was from Docusign and that the contents are the exact same as the time of sending.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).

Code example:

The code example below contains a simple createEnvelope call with the event notification enabled for using the JSON SIM format and HMAC. I have included all events and all event data to be included, so you could cut those lists down to be as small as you’d like. You need at least one event, but you can remove all of the event data in includedData and just pass an empty array, if you wouldn’t like any of that information back.

{
  "status": "sent",
  "documents": [{
      "documentId": "1",
      "name": "TestDocument.docx",
      "fileExtension": "docx",
      "documentBase64": ""UEsDBBQABgAIAAAAIQDfpNJsWgEAACAFAAAT......"
    }
  ],
  "recipients": {
    "signers": [{
        "name": "John Doe",
        "email": "jdoe@example.com",        
        "recipientId": "1",
        "tabs": {
          "signHereTabs": [{
              "xPosition": "25",
              "yPosition": "50",
              "documentId": "1",
              "pageNumber": "1"
            }
          ]
        }
      }
    ]
  },
  "eventNotification":{
    "url": "https://webhook.site/f184a92f........."
    "requireAcknowledgment": "true",
    "loggingEnabled": "true",
    "deliveryMode": "SIM",
    "integratorManaged": "true",
    "includeHMAC": "true",
    "events":[
        "envelope-sent",
        "envelope-resent",
        "envelope-delivered",
        "envelope-completed",
        "envelope-declined",
        "envelope-voided",
        "recipient-authenticationfailed",
        "recipient-autoresponded",
        "recipient-declined",
        "recipient-delivered",
        "recipient-completed",
        "recipient-sent",
        "recipient-resent",
        "envelope-corrected",
        "envelope-purge",
        "envelope-deleted",
        "recipient-reassign",
        "recipient-finish-later",
        "recipient-delegate"
    ],
    "eventData":{
        "version": "restv2.1",
        "includeData":[
            "attachments",
            "custom_fields",
            "documents",
            "extensions",
            "folders",
            "payment_tabs",
            "powerform",
            "prefill_tabs",
            "recipients",
            "tabs"
        ]
    }
  }
}

In the above code block, there are a few important parameters to point out. First, for the JSON SIM format, you need to ensure that you’re specifying the deliveryMode as SIM and the version in event data as restv2.1. This tells the API that you would like to use the JSOM SIM format instead of the legacy XML format for your event messages.

Secondly, I have specified includeHMAC as true and integratorManaged as true as well. The includeHMAC parameter ensures that HMAC is used in your call, but the integratorManaged parameter enables you to use your HMAC key to validate messages for other accounts, which is handy if you have customers using your listener, but you don’t want them to have to create HMAC keys and manage those. You just have to ensure that the other accounts are using your integration key.

If you don’t plan on managing other users’ event messages, you can remove the integratorManaged parameter from the call; and if you don’t want to use HMAC, you can just remove the includeHMAC parameter from the call as well.

Additional resources

Jonathan SammonsDeveloper Support Engineer

Jonathan Sammons is a Docusign Developer Support Engineer based in the Dublin, Ireland office who has a passion for new technologies. He’s been with Docusign for over 8 years in various support roles.