--- title: "Request Signing" slug: "request-signing" description: "Discover the importance of using a Signing Key when setting up a Lookup Adaptor and learn how it enhances request security." updated: 2026-05-06T14:33:21Z published: 2026-05-06T14:33:21Z canonical: "help.gladly.com/request-signing" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.gladly.com/llms.txt > Use this file to discover all available pages before exploring further. # Request Signing ## Setup When setting up a Lookup Adaptor, you must supply a [Signing Key](https://help.gladly.com/docs/set-up-and-edit-custom-integration), 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 > [!CAUTION] > 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: ```plaintext https://example.organization.com/api/v2/customer/lookup ``` With signing key: ```plaintext test-apikey-1 ``` And payload body: ```plaintext {"lookupLevel":"DETAILED","query":{"emails":["martha.williams@gmail.com"],"externalCustomerId":"abc","favoriteDate":"2018-08-19T07:00:00.000Z","favoriteFood":"Apple Pie","id":"o2sg-TMTSD2rTwMuxzewbA","name":"Martha Williams","phones":["+15013299800"]},"uniqueMatchRequired":true} ``` And headers: ```plaintext 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): ```plaintext 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: ```plaintext 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: ```plaintext 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 ```plaintext hmac(byte[]("test-apikey-1"), "20190213") ``` which produces the byte array: ```plaintext 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 ```plaintext 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: ```plaintext 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 ```plaintext 4c633fca4914f51df04c9ec40f4545d66d653e771c6634e33eed52a242bc278c ``` #### Step 4: Include signature in a header ```plaintext -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.