3.2 HMAC Authentication

HMAC is a secure standard that is used to authenticate that a request is unique and comes from a trusted source. It is more complicated to implement than the API key method but has several advantages.

•    Public key exposed in the security header cannot be used if intercepted without knowledge of the private key.

•    Hashed signature that both the client and server understand prevent Man in the Middle attacks.

•    Timestamp and unique nonce prevent Delay and Replay attacks.

When you create a webhook with HMAC credentials a public and private key are generated. The public key is sent over the network and is simply used as a lookup for the private key to allow verification of HMAC signatures.

3.2.1 Generating a HMAC

The HMAC is sent in the authorization header using the HMAC authentication scheme. It is in the following format.

Example 

The below subsections show how each part of the header is calculated.

3.2.1.1 Public Key

The public key is pulled directly from the database from the webhook entity.

3.2.1.2 Signature

The signature is calculated by linking the following strings together in order with no spaces.

1.    The request URI (webhook endpoint) all lower case 

2.    The request Method, which is always ‘POST’ in our implementation.

3.    An unsalted MD5 of the body of the request as a base 64 string.

4.    A randomly generated string to use as a nonce.

5.    The Unix timestamp of the request being made (Seconds since Epoch)

Once the above string is built it is put through the SHA256 algorithm using the secret key that maps to the public key of the request.

The resulting byte array is then Converted to a Base64 string.

3.2.1.3 Nonce

The nonce is a randomly generated string that may be used by consumers to ensure that requests are only processed once, in our implementation this string is a generated GUID with no dashes.

3.2.1.4 UnixTimestamp

The time in unix format     (Seconds since Epoch)

3.2.2 Example Code (c#)

Coming Soon...