docs(ootbc): add HMAC scopes description in http-webhook.md (#2395)

docs/components/connectors/protocol/http-webhook.md

@@ -25,11 +25,51 @@ Please refer to the [update guide](/guides/update-guide/connectors/060-to-070.md
 ## Make your HTTP Webhook Connector executable
 
 1. In the **Webhook Configuration** section, configure the **Webhook ID**. By default, **Webhook ID** is pre-filled with a random value. This value will be part of the Webhook URL. You will find more details about HTTP Webhook URLs [below](#activate-the-http-webhook-connector-by-deploying-your-diagram).
-2. Configure [HMAC authentication](https://en.wikipedia.org/wiki/HMAC) if required.
+2. Configure [**HMAC authentication**](https://en.wikipedia.org/wiki/HMAC):
+ If you require HMAC authentication for your webhook, you can set up the HMAC shared secret key, HMAC header, HMAC hash algorithm, and an array of HMAC scopes.
 
-- Set the HMAC shared secret key which is used to calculate the message hash. The value is defined by a webhook administrator.
-- Set the HMAC header whose value contains an encrypted hash message. The exact value is provided by the external caller.
-- Select HMAC hash algorithm. The exact value is provided by the external caller.
+ - **HMAC secret key**: Set the HMAC shared secret key that will be used to calculate the message hash. The value of this key should be provided by the webhook provider to ensure secure communication.
+ - **HMAC header**: Set the HMAC header whose value contains an encrypted hash message. The exact value of this header should be provided by the external caller when invoking your webhook.
+ - **HMAC hash algorithm**: Select the HMAC hash algorithm to be used in the HMAC signature calculation. The exact value of this algorithm should also be provided by the external caller when invoking your webhook.
+ - **HMAC Scopes** (optional): Here, you can define an array of HMAC scopes to specify which parts of the webhook request are included in the HMAC signature calculation. The available HMAC scopes are:
+
+ - `BODY` (default value): Includes the body of the webhook request in the HMAC signature calculation.
+ - `URL`: Includes the URL of the webhook request in the HMAC signature calculation.
+ - `PARAMETERS`: Includes the query parameters of the URL in the HMAC signature calculation.
+
+ Example: `=["URL","PARAMETERS"]`
+
+ Based on the selected HMAC scopes and the HTTP method used in the webhook request, the system will automatically determine the appropriate HMAC strategy to be used. The supported HMAC strategies are:
+
+ - **Body Encoding Strategy (default)**: This strategy is used when the HMAC scopes only include `BODY` or empty. The signature data for the HMAC signature is generated from the body of the webhook request.
+
+ - **URL and Parameters Encoding Strategy**: This strategy is used when the HMAC scopes include `URL`, and `PARAMETERS`, and the HTTP method is `GET`. The signature data for the HMAC signature is generated by combining the URL and the parameters of the webhook request.
+
+ - **URL and Body Encoding Strategy**: This strategy is used when the HMAC scopes include `URL`, `BODY`. When the HTTP method is `GET`, it uses the **URL and Parameters Encoding Strategy** instead. The signature data for the HMAC signature is generated by combining the URL and the body of the webhook request.
+
+ **Example for URL and Parameters Encoding Strategy**:
+ Let's consider a sample webhook request:
+
+ ```
+ HTTP Method: GET
+ Webhook URL: "https://example.com/webhook?id=123456&name=John%20Doe"
+ ```
+
+ In this example, the HMAC strategy will combine the URL and the query parameters to generate the signature data for the HMAC signature. The URL-encoded query parameters will be sorted alphabetically, and then, they will be concatenated with the URL: Signature Data: `https://example.com/webhook?name=John%20Doe&id=123456`
+ The `Signature Data` will then be used to calculate the HMAC signature using the provided secret key and hash algorithm.
+
+ **Example for URL and Body Encoding Strategy**:
+ Let's consider another sample webhook request:
+
+ ```
+ HTTP Method: POST
+ Webhook URL: `https://example.com/webhook`
+ Webhook Body: `{"id": 123456, "name": "John Doe", "age": 30}`
+ ```
+
+ In this example, the HMAC strategy will combine the URL and the body of the webhook request to generate the signature data for the HMAC signature:
+ Signature Data: `https://example.com/webhook{"id":123456,"name":"John Doe","age":30}`
+ The `Signature Data` will then be used to calculate the HMAC signature using the provided secret key and hash algorithm.
 
 3. Configure **Activation Condition**. For example, given external caller triggers a webhook endpoint with the body `{"id": 1, "status": "OK"}`, the **Activation Condition** value might look like `=(request.body.status = "OK")`. Leave this field empty to trigger your webhook every time.
 4. Use **Variable Mapping** to map specific fields from the request into process variables using [FEEL](/components/modeler/feel/what-is-feel.md).

versioned_docs/version-8.1/components/connectors/protocol/http-webhook.md

@@ -25,11 +25,51 @@ Please refer to the [update guide](/guides/update-guide/connectors/060-to-070.md
 ## Make your HTTP Webhook Connector executable
 
 1. In the **Webhook Configuration** section, configure the **Webhook ID**. By default, **Webhook ID** is pre-filled with a random value. This value will be part of the Webhook URL. You will find more details about HTTP Webhook URLs [below](#activate-the-http-webhook-connector-by-deploying-your-diagram).
-2. Configure [HMAC authentication](https://en.wikipedia.org/wiki/HMAC) if required.
+2. Configure [**HMAC authentication**](https://en.wikipedia.org/wiki/HMAC):
+ If you require HMAC authentication for your webhook, you can set up the HMAC shared secret key, HMAC header, HMAC hash algorithm, and an array of HMAC scopes.
 
-- Set the HMAC shared secret key which is used to calculate the message hash. The value is defined by a webhook administrator.
-- Set the HMAC header whose value contains an encrypted hash message. The exact value is provided by the external caller.
-- Select HMAC hash algorithm. The exact value is provided by the external caller.
+ - **HMAC secret key**: Set the HMAC shared secret key that will be used to calculate the message hash. The value of this key should be provided by the webhook provider to ensure secure communication.
+ - **HMAC header**: Set the HMAC header whose value contains an encrypted hash message. The exact value of this header should be provided by the external caller when invoking your webhook.
+ - **HMAC hash algorithm**: Select the HMAC hash algorithm to be used in the HMAC signature calculation. The exact value of this algorithm should also be provided by the external caller when invoking your webhook.
+ - **HMAC Scopes** (optional): Here, you can define an array of HMAC scopes to specify which parts of the webhook request are included in the HMAC signature calculation. The available HMAC scopes are:
+
+ - `BODY` (default value): Includes the body of the webhook request in the HMAC signature calculation.
+ - `URL`: Includes the URL of the webhook request in the HMAC signature calculation.
+ - `PARAMETERS`: Includes the query parameters of the URL in the HMAC signature calculation.
+
+ Example: `=["URL","PARAMETERS"]`
+
+ Based on the selected HMAC scopes and the HTTP method used in the webhook request, the system will automatically determine the appropriate HMAC strategy to be used. The supported HMAC strategies are:
+
+ - **Body Encoding Strategy (default)**: This strategy is used when the HMAC scopes only include `BODY` or empty. The signature data for the HMAC signature is generated from the body of the webhook request.
+
+ - **URL and Parameters Encoding Strategy**: This strategy is used when the HMAC scopes include `URL`, and `PARAMETERS`, and the HTTP method is `GET`. The signature data for the HMAC signature is generated by combining the URL and the parameters of the webhook request.
+
+ - **URL and Body Encoding Strategy**: This strategy is used when the HMAC scopes include `URL`, `BODY`. When the HTTP method is `GET`, it uses the **URL and Parameters Encoding Strategy** instead. The signature data for the HMAC signature is generated by combining the URL and the body of the webhook request.
+
+ **Example for URL and Parameters Encoding Strategy**:
+ Let's consider a sample webhook request:
+
+ ```
+ HTTP Method: GET
+ Webhook URL: "https://example.com/webhook?id=123456&name=John%20Doe"
+ ```
+
+ In this example, the HMAC strategy will combine the URL and the query parameters to generate the signature data for the HMAC signature. The URL-encoded query parameters will be sorted alphabetically, and then, they will be concatenated with the URL: Signature Data: `https://example.com/webhook?name=John%20Doe&id=123456`
+ The `Signature Data` will then be used to calculate the HMAC signature using the provided secret key and hash algorithm.
+
+ **Example for URL and Body Encoding Strategy**:
+ Let's consider another sample webhook request:
+
+ ```
+ HTTP Method: POST
+ Webhook URL: `https://example.com/webhook`
+ Webhook Body: `{"id": 123456, "name": "John Doe", "age": 30}`
+ ```
+
+ In this example, the HMAC strategy will combine the URL and the body of the webhook request to generate the signature data for the HMAC signature:
+ Signature Data: `https://example.com/webhook{"id":123456,"name":"John Doe","age":30}`
+ The `Signature Data` will then be used to calculate the HMAC signature using the provided secret key and hash algorithm.
 
 3. Configure **Activation Condition**. For example, given external caller triggers a webhook endpoint with the body `{"id": 1, "status": "OK"}`, the **Activation Condition** value might look like `=(request.body.status = "OK")`. Leave this field empty to trigger your webhook every time.
 4. Use **Variable Mapping** to map specific fields from the request into process variables using [FEEL](/components/modeler/feel/what-is-feel.md).

versioned_docs/version-8.2/components/connectors/protocol/http-webhook.md

@@ -25,11 +25,51 @@ Please refer to the [update guide](/guides/update-guide/connectors/060-to-070.md
 ## Make your HTTP Webhook Connector executable
 
 1. In the **Webhook Configuration** section, configure the **Webhook ID**. By default, **Webhook ID** is pre-filled with a random value. This value will be part of the Webhook URL. You will find more details about HTTP Webhook URLs [below](#activate-the-http-webhook-connector-by-deploying-your-diagram).
-2. Configure [HMAC authentication](https://en.wikipedia.org/wiki/HMAC) if required.
+2. Configure [**HMAC authentication**](https://en.wikipedia.org/wiki/HMAC):
+ If you require HMAC authentication for your webhook, you can set up the HMAC shared secret key, HMAC header, HMAC hash algorithm, and an array of HMAC scopes.
 
-- Set the HMAC shared secret key which is used to calculate the message hash. The value is defined by a webhook administrator.
-- Set the HMAC header whose value contains an encrypted hash message. The exact value is provided by the external caller.
-- Select HMAC hash algorithm. The exact value is provided by the external caller.
+ - **HMAC secret key**: Set the HMAC shared secret key that will be used to calculate the message hash. The value of this key should be provided by the webhook provider to ensure secure communication.
+ - **HMAC header**: Set the HMAC header whose value contains an encrypted hash message. The exact value of this header should be provided by the external caller when invoking your webhook.
+ - **HMAC hash algorithm**: Select the HMAC hash algorithm to be used in the HMAC signature calculation. The exact value of this algorithm should also be provided by the external caller when invoking your webhook.
+ - **HMAC Scopes** (optional): Here, you can define an array of HMAC scopes to specify which parts of the webhook request are included in the HMAC signature calculation. The available HMAC scopes are:
+
+ - `BODY` (default value): Includes the body of the webhook request in the HMAC signature calculation.
+ - `URL`: Includes the URL of the webhook request in the HMAC signature calculation.
+ - `PARAMETERS`: Includes the query parameters of the URL in the HMAC signature calculation.
+
+ Example: `=["URL","PARAMETERS"]`
+
+ Based on the selected HMAC scopes and the HTTP method used in the webhook request, the system will automatically determine the appropriate HMAC strategy to be used. The supported HMAC strategies are:
+
+ - **Body Encoding Strategy (default)**: This strategy is used when the HMAC scopes only include `BODY` or empty. The signature data for the HMAC signature is generated from the body of the webhook request.
+
+ - **URL and Parameters Encoding Strategy**: This strategy is used when the HMAC scopes include `URL`, and `PARAMETERS`, and the HTTP method is `GET`. The signature data for the HMAC signature is generated by combining the URL and the parameters of the webhook request.
+
+ - **URL and Body Encoding Strategy**: This strategy is used when the HMAC scopes include `URL`, `BODY`. When the HTTP method is `GET`, it uses the **URL and Parameters Encoding Strategy** instead. The signature data for the HMAC signature is generated by combining the URL and the body of the webhook request.
+
+ **Example for URL and Parameters Encoding Strategy**:
+ Let's consider a sample webhook request:
+
+ ```
+ HTTP Method: GET
+ Webhook URL: "https://example.com/webhook?id=123456&name=John%20Doe"
+ ```
+
+ In this example, the HMAC strategy will combine the URL and the query parameters to generate the signature data for the HMAC signature. The URL-encoded query parameters will be sorted alphabetically, and then, they will be concatenated with the URL: Signature Data: `https://example.com/webhook?name=John%20Doe&id=123456`
+ The `Signature Data` will then be used to calculate the HMAC signature using the provided secret key and hash algorithm.
+
+ **Example for URL and Body Encoding Strategy**:
+ Let's consider another sample webhook request:
+
+ ```
+ HTTP Method: POST
+ Webhook URL: `https://example.com/webhook`
+ Webhook Body: `{"id": 123456, "name": "John Doe", "age": 30}`
+ ```
+
+ In this example, the HMAC strategy will combine the URL and the body of the webhook request to generate the signature data for the HMAC signature:
+ Signature Data: `https://example.com/webhook{"id":123456,"name":"John Doe","age":30}`
+ The `Signature Data` will then be used to calculate the HMAC signature using the provided secret key and hash algorithm.
 
 3. Configure **Activation Condition**. For example, given external caller triggers a webhook endpoint with the body `{"id": 1, "status": "OK"}`, the **Activation Condition** value might look like `=(request.body.status = "OK")`. Leave this field empty to trigger your webhook every time.
 4. Use **Variable Mapping** to map specific fields from the request into process variables using [FEEL](/components/modeler/feel/what-is-feel.md).