Request Signing

New
  • Published on Jan 30, 2025
  • 2 minute(s) read

Setup

When setting up a Lookup Adaptor, you must supply a Signing Key, which is used to create a Gladly request signature. We recommend choosing a key with good strength (128-bit secure random value or larger).

Use this key in conjunction with HMAC SHA-256 to sign the message content, enabling you to verify the request's authenticity and integrity.

How requests are signed

Watch Out - Don't hardcode headers

Don't hardcode header values in your code when calculating the request signature. Some requests (e.g., Submit Action Form, Retrieve Action Form) may have additional headers that other requests do not.

Example scenario

With an example lookup to:

https://example.organization.com/api/v2/customer/lookup

With signing key:

test-apikey-1

And payload body:

{"lookupLevel":"DETAILED","query":{"emails":["[email protected]"],"externalCustomerId":"abc","favoriteDate":"2018-08-19T07:00:00.000Z","favoriteFood":"Apple Pie","id":"o2sg-TMTSD2rTwMuxzewbA","name":"Martha Williams","phones":["+15013299800"]},"uniqueMatchRequired":true}

And headers:

Content-Type: application/json
Accept: application/json
Gladly-Correlation-Id: vXmSEPjVSWCaCMzvjufxZg
X-B3-Traceid: bd799210f8d549609a08ccef8ee7f166
Gladly-Time: 20190213T214016Z

Signing Steps

Step 1: Normalize the request

Normalize the request by using a newline to join the following into a single string:

  • Request method: POST

  • URI path (as configured in App Settings): /api/v2/customer/lookup

  • sorted query parameters (case sensitive). Gladly does not send GET parameters to your Customer Lookup integration unless you specify them in the URL of the integration you set up or in an Action. In the example above, this value is blank.

  • sorted headers keys and values joined. The header keys should be lower cased and leading and trailing white space should be removed from both keys and values. Only use the headers provided in the SignedHeaders value of the header Gladly-Authorization. This will include a time header.accept:application/json content-type:application/json gladly-correlation-id:vXmSEPjVSWCaCMzvjufxZg gladly-time:20190213T214016Z x-b3-traceid:bd799210f8d549609a08ccef8ee7f166

    • Note If you are using Salesforce: Salesforce strips the Authorization header. You will need to hardcode Authorization: Basic${base64encode(username:password)} header when evaluating the request. Salesforce replaces the x-b3-traceid header with a random string of length 16 instead of preserving the Gladly string of length 32. To manually calculate x-b3-traceid, you will need to encode gladly-correlation-id to Base64 format and then convert it to hex.

  • sorted header keys: accept;content-type;gladly-correlation-id;gladly-time;x-b3-traceid

  • lower case hex of the request body hashed with SHA256: f187462a1d8e09bc86ea4b4ff8c022e5e4ed23ae783b3b1b5baee4b8d69e02ca

Which, when joined will create a string (note that the empty lines are intentional):

POST
 /api/v2/customer/lookup
 accept:application/json
 content-type:application/json
 gladly-correlation-id:vXmSEPjVSWCaCMzvjufxZg
 gladly-time:20190213T214016Z
 x-b3-traceid:bd799210f8d549609a08ccef8ee7f166

 accept;content-type;gladly-correlation-id;gladly-time;x-b3-traceid
 f187462a1d8e09bc86ea4b4ff8c022e5e4ed23ae783b3b1b5baee4b8d69e02ca

And then hashed using sha256 then, converted to hex and lowercased:

f96c13077adb3c06df1fa5fda8a6f32d7067735f63aa58d47e45fd6429d3cad3

Step 2: Create signing string

Create a string to be signed by using a newline to join the following into a single string:

  • name of the signing algorithm: hmac-sha256

  • date and time (will be the same as the Gladly-Time header above): 20190213T214016Z

  • encoded normalized request from step 1 above: f96c13077adb3c06df1fa5fda8a6f32d7067735f63aa58d47e45fd6429d3cad3

Which, joined together will look like this:

 hmac-sha256
 20190213T214016Z
 f96c13077adb3c06df1fa5fda8a6f32d7067735f63aa58d47e45fd6429d3cad3

Step 3: Sign the string

Create a salted signing key by signing the date with the Request Signature specified at the top

hmac(byte[]("test-apikey-1"), "20190213")

which produces the byte array:

99 38 140 149 41 195 7 213 98 131 123 175 98 47 132 215 126 39 114 255 99 79 167 25 45 219 131 221 3 152 116 126

create a signature by signing the string to be signed with the salted signing key

hmac([99 38 140 149 41 195 7 213 98 131 123 175 98 47 132 215 126 39 114 255 99 79 167 25 45 219 131 221 3 152 116 126], "hmac-sha256\n20190213T214016Z\nf96c13077adb3c06df1fa5fda8a6f32d7067735f63aa58d47e45fd6429d3cad3"

which produces the byte array:

76 99 63 202 73 20 245 29 240 76 158 196 15 69 69 214 109 101 62 119 28 102 52 227 62 237 82 162 66 188 39 140

encode as a hex string

4c633fca4914f51df04c9ec40f4545d66d653e771c6634e33eed52a242bc278c

Step 4: Include signature in a header

 -H "Gladly-Authorization: SigningAlgorithm=hmac-sha256, SignedHeaders=accept;content-type;gladly-correlation-id;gladly-time;x-b3-traceid, Signature=4c633fca4914f51df04c9ec40f4545d66d653e771c6634e33eed52a242bc278c

The signed headers are provided in a semicolon-delimited list, sorted alphabetically.

Related docs