Create a Trigger Connection Definition Using HMAC Signatures

This procedure gives an overview of how to create a trigger connection definition with a security policy that uses hash-based message authentication code (HAMC) signature.

Prerequisites:

Check the webhook producer documentation on how the webhook is signed. Collect information on the following:

• What is signed?
• Which algorithm is used.
• How the signature is sent in the request? For example, find out which header and the format of the header value.
• Does it contain any information on timestamp to be validated. If yes where and what format.
• How to get the signing key?

1. Open the adapter definition document in Visual Studio Code Editor.
2. Navigate to the connection code section of the document and set the scope to TRIGGER.
3. Set the value of the security properties according to the information you collected in the prerequisites.

   Here is a code sample where:

   • Signature is computed by signing request body (.request.body).
   • Signature key is added in securityProperty signKey part of same policy and referred in HMAC function (.securityProperties.signKey).
   • Signature to match is present in HTTP header x-hub-signature-256.
   • Timestamp validation is not required and hence empty string.

   "securityPolicies": [
        {  
           "type": "managed",
           "refName": "HMAC_SIGNATURE_VALIDATION",
           "description": "Validates HMAC Signature",
           "displayName": "HMAC SIGNATURE VALIDATION",
           "scope": "TRIGGER",
           "securityProperties": [
              {
                  "name": "signature",
                  "hidden": true,
                  "required": true,
                  "default": "${connectivity::hexDecode(.request.headers.digest)}"
              },
              {
                  "name": "signatureString",
                  "displayName": "Request Signature Location",
                  "hidden": true,
                  "required": true,
                  "default": "${.request.body}"
              },
              {
                  "name": "signatureAlgorithm",
                  "displayName": "Request Signature Location",
                  "hidden": true,
                  "required": true,
                  "default": "HMACSHA256"
              },
              {
                  "name": "secret",
                  "displayName": "Shared Secret",
                  "hidden": false,
                  "default": true
              },
              {
                  "name": "timestampValidator",
                  "displayName": "Timestamp Validation",
                  "hidden": true,
                  "required": true,
                  "default": ""
              },
               
          ]
         }
      ]

   Here is another code sample where:

   • Signature is computed by signing request body (.request.body).
   • Signature key is added in securityProperty signKey part of same policy and referred in HMAC function (.securityProperties.signKey).
   • Signature to match is present in HTTP header x-hub-signature-256.
   • Timestamp validation is done against header x-timestamp. In this sample code, the timestamp is after current time and valid for only five minutes.

   {
    "connection": {
        
       "securityPolicies": [
        { 
           "type": "managed",
           "refName": "HMAC_SIGNATURE_VALIDATION",
           "description": "Validates HMAC Signature",
           "displayName": "HMAC SIGNATURE VALIDATION",
           "scope": "TRIGGER",
           "securityProperties": [
              {
                  "name": "signature",
                  "hidden": true,
                  "required": true,
                  "default": "${connectivity::base64Decode(.request.headers.digest)}"
              },
              {
                  "name": "signatureString",
                  "hidden": true,
                  "required": true,
                  "default": "${.request.body}"
              },
              {
                  "name": "signatureAlgorithm",
                  "displayName": "Request Signature Location",
                  "hidden": true,
                  "required": true,
                  "default": "HMACSHA256"
              },
              {
                  "name": "secret",
                  "displayName": "Shared Secret",
                  "hidden": false,
                  "required": true
              },
              {
               "name": "timestampValidator",
               "displayName": "Shared Secret",
               "hidden": true,
               "required": true,
               "default": "(.request.headers."x-timestamp"|tonumber <= (now*1000)) and  ((now*1000)-(.request.headers."x-timestamp"|tonumber) <=300000 ) "
             }
                
          ]
         }
      ]
     }
   }