How to validate an HMAC signature

This topic demonstrates an example workflow for a client app receiving and validating a webhook (Docusign Connect) message using HMAC security.

Prerequisites

• The account administrator must have Docusign Connect (webhooks) enabled in your Docusign account. See Enable Connect for details.
• In your Docusign account, you must have created a custom Connect configuration and added an HMAC key.
• You must have also triggered and examined a test event (sent an envelope).

Compute the HMAC hash

1. Extract the text of the plain text JSON payload as an array of bytes. The entire body of the POST request is used, including line endings.
2. Compute a SHA256 HMAC hash for the array of bytes.
3. Base64-encode the hash.

public static string ComputeHash(string secret, string payload)
{
    byte[] bytes = Encoding.UTF8.GetBytes(secret);
    var hmac = new HMACSHA256(bytes);
    bytes = Encoding.UTF8.GetBytes(payload);
    return Convert.ToBase64String(hmac.ComputeHash(bytes));
}
public static bool HashIsValid(string secret, string payload, string verify)
{
    ReadOnlySpan<byte> hashBytes = Convert.FromBase64String(ComputeHash(secret, payload));
    ReadOnlySpan<byte> verifyBytes = Convert.FromBase64String(verify);
    return CryptographicOperations.FixedTimeEquals(hashBytes, verifyBytes);
}

Expected response

If you run this code example from our Quickstart or launcher projects, you should see a base64-encoded HMAC hash.

Compare the base64 hash to the values of the x-docusign-signature header. There will be one x-docusign-signature header value for each HMAC key configured for your account: the first signature is in header x-docusign-signature-1, the second in x-docusign-signature-2, etc.

Compare the one you computed using your application’s HMAC key(s). At least one of the computed hashes must exactly match its corresponding header value. If there is no match, then the notification may be compromised and it should not be trusted. Only one match is required.

If you experience errors:

• Make sure that the payload is correct as a string. You’ll need to use the correct string encoding to read the Connect payload from bytes sent on the network wire.
• If the secret has any " characters, remove them before the computation.

Next steps

• Run this code example from our Quickstart or launcher projects: C#, Java, Node.js, PHP, Python, or Ruby.
• Learn more about Docusign Connect.
• Learn how to add and remove HMAC keys from your Docusign Connect configuration.
• See Using HMAC Security with Docusign Connect.