Webhooks and Session Data and Cloud Secrets

Introduction

This document will describe the steps required to take advantage of placeholder variable substitution when sending Webhooks from TrustX.

Variable substitution is used to generate the webhook headers and body at the time of the webhook execution. This allows for the substitution of variable for secrets or for the inclusion of specific data related to the process instance at the time of execution.

This document will describe the steps required to take advantage of Session Data when sending webhooks from TrustX. For more information on Session Data, see the Session Data page.

Also covered in this document will be utilizing Cloud Secrets within a webhook. For more information on Cloud Secrets, see the Cloud Secrets Guide.

Three scenarios will be covered including the following use cases:

  1. Sending a webhook using Session Data.
  2. Sending a webhook using a Cloud Secret in the request body.
  3. Sending a webhook using a Cloud Secret in the request header.

Webhook and Session Data

Session Data can be included as part of the request body of a webhook. First, follow the steps to create a webhook as outlined in the Webhooks Guide by navigating to the 'Webhooks' tab on the left-navigation bar. On this page, select the orange 'New Webhook' button.

Clicking this button will open the webhook creation page. Enter details about the webhook such as name and description, then select the 'Body' option from the list of available tabs.

Placeholder variables for substitution can be placed anywhere in the body of the webhook. To define a session data placeholder to substitute the placeholder must follow the format {{processvar._myjsonpathexpression_}}" i.e.

  • a prefix of: {{processvar.
  • a JSONPath expression to query the session data
  • and a suffix of: }}

JSONPath is a query language used to navigate and extract data from JSON documents. It provides a way to specify a path expression that points to a specific part of the JSON data, allowing you to retrieve the desired information efficiently.

Webhooks used JSONPath expressions as a way to traverse the 'session data' structure and extract information to include when sending the webhook.

Simple Example:

In this example we include a single piece of information in the webhook - the issuing state name for the document.

JSON
Copy

The JSON includes the "issuingStateName" and the value is evaluated using variable substitution as the value in the format of a placeholder variable: {{processvar.}}

The placeholder variable contains a JSON path expression: _idDocs["doc1"].currentDocumentCapture.processorResults["documentProcessorDocInfo"].issuingStateName.

The JSONPath expression can be broken down as follows:

  1. _idDocs["doc1"]: This part points to an Document object with the key "doc1" inside an object named _idDocs.
  2. .currentDocumentCapture: After finding the Document with the key "doc1" the expression references the currentDocumentCapture object (DocumentCapture) of the Document.
  3. .processorResults["documentProcessorDocInfo"]: Now that we have the DocumentCapture, we are looking for a processing result named "documentProcessorDocInfo".
  4. .issuingStateName: Now that we have the DocumentProcessorDocInfo, we retrieve the object's issuingStateName for inclusion.

When executing the webhook as part of a process definition, the following webhook will be received.

JSON
Copy

Further Examples:

Webhooks variable substitution can index into all of the data included in session data, in the examples below we will look to demonstrate some of the more common use cases:

Including a Complex Type

Variable substitution is not limited to 'leaf' elements such as .issuingStateName discussed above, complex types can also be included. In the example below we include the document processing 'info' i.e. the general information about the recognized document.

JSON
Copy

The JSON includes the "docInfo" and the value is evaluated using variable substitution as the value in the format of a placeholder variable: {{processvar.}}

The placeholder variable contains a JSON path expression: _idDocs[\"doc1\"].currentDocumentCapture.processorResults[\"documentProcessorDocInfo\"].

The JSONPath expression can be broken down as follows:

  1. _idDocs["doc1": This part points to an Document object with the key "doc1" inside an object named _idDocs.
  2. .currentDocumentCapture: After finding the Document with the key "doc1" the expression references the currentDocumentCapture object (DocumentCapture) of the Document.
  3. .processorResults["documentProcessorDocInfo"]: Now that we have the DocumentCapture, we are looking for a processing result named "documentProcessorDocInfo". The documentProcessorDocInfo provides information about the document that was recognized and some basic attributes of the document.
JSON
Copy

Including a _checks results

Check the result of a specific check can be achieved as follows:

JSON
Copy

The JSON includes the "documentQualityOutcome" and the value is evaluated using variable substitution as the value in the format of a placeholder variable: {{processvar.}}

The placeholder variable contains a JSON path expression: _checks.visualIntegrity.doc1.front.documentQuality.outcome.

  1. _checks": This part points to an checks object (a map of values).
  2. .visualIntegrity.doc1.front: After finding the Checks the expression references the visualIntegrity.doc1.front checks.
  3. .documentQuality.outcome: Now that we have the checks, we are referencing the outcome of documentQuality check.

When executing the webhook as part of a process definition the following webhook will be received.

JSON
Copy

Including Additional Token Parameters in a Webhook

Additional Parameters defined in the creation of a Process Token are accessible from the _initVars variable.

Additional Parameters can be accessed by using the key of the Additional Parameter. For example, to access the "email' value, users can use:

JSON
Copy

The JSON includes the "tokenInfo" and the value is evaluated using variable substitution as the value in the format of a placeholder variable: {{processvar._initVars.params[\"email\"]}}

  1. _initVars": This part points to a _initVars object (a map of values).
  2. .params[\"email\"]: Accesses the parameters of the _initVars object and retrieves the email.

_initVars.params refers to the Initial Variable parameters. In this case, the "email" parameter can be retrieved and sent from the Webhook.

When the Webhook is sent, the user will receive the following information:

JSON
Copy

Cloud Secrets in the Request Header

This section will discuss using Cloud Secrets in the request header of a webhook. Navigate to the webhook creation page and select the 'Headers' tab. Click the green 'Add New Header' button to add an additional header key-value pair.

The key represents the variable name. The value will store the Cloud Secret.

Example:

In this example we want to add a Header called X-API-Key to provide authentication, the secret to be included is selected from the available 'cloud secrets'.

Once all Header entries are set, click the 'Save' button at the bottom-right of the screen to complete the webhook creation.

When executing the webhook as part of a process definition the following webhook headers will be received including the cloud secret set above - X-API-Key:

Note: When setting an Authorization header with a bearer token, the cloud secret value should be set as Bearer {mytoken}.

Cloud Secrets in the Request Body

This section will discuss using Cloud Secrets in the request body of a webhook. Similar to using Session Data with webhooks, Cloud Secrets can be implemented when creating a new webhook and selecting the 'Body' tab.

To use a Cloud Secret in the request body, the format "mysecret": "{{cloudsecret._yoursecret_}}" is used.

Example:

JSON
Copy

Once the Body is finalized, click the 'Save' button at the bottom-right of the screen to complete the webhook creation.

When executing the webhook as part of a process definition the following webhook will be received.

Response Example

JSON
Copy

Testing Webhooks

Various testing tools are available online such as webhook.site and typedwebhook.tools that can be used for testing webhooks. Note that Daon cannot provide support for any third party applications or tools, including the tools listed in this document.

Type to search, ESC to discard
Type to search, ESC to discard
Type to search, ESC to discard
Next to read:
Custom Data Forms
Edit on GitHub
On This Page
Webhooks and Session Data and Cloud SecretsIntroductionWebhook and Session DataFurther Examples:Including a Complex TypeIncluding a _checks resultsIncluding Additional Token Parameters in a WebhookCloud Secrets in the Request HeaderCloud Secrets in the Request BodyTesting Webhooks