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 authenticity and integrity of the request.
How requests are signed #
Example scenario #
With an example lookup to:
Text
https://example.organization.com/api/v2/customer/lookup
With signing key:
Text
test-apikey-1
And payload body:
Text
{"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:
Text
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 headerGladly-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):
Text
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
Text
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:
Text
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.
Text
hmac(byte[]("test-apikey-1"), "20190213")
which produces the byte array:
Text
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
Text
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:
Text
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
Text
4c633fca4914f51df04c9ec40f4545d66d653e771c6634e33eed52a242bc278c
Step 4: Include signature in a header #
Text
-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.