Webhook settings

Webhook in SimWorkflow provides for loose coupling between workflows and support for consuming events from external systems.

To configure workflow definition webhook settings:

  1. Log in to the SimWorkflow.

  2. Navigate to Workflow definitions.

  3. For a specific workflow definition, select the Webhook settings menu in the 3 dots dropdown menu.

  4. Configure the webhook settings.

From the workflow definition webhook settings page, set up the following fields:

Field

Required

Description

Webhook on

No

Whether the Webhook should be on or off.

Workflow definition version

No

Lock to a specific version of the workflow definition. If not set, the latest version will be used.

User to start the workflow as

Yes

The active user to start the workflow as.

Verification request response

No

A configuration for verification request response represented by a JSON Object.

Validate the payload

No

JavaScript expression and may be evaluated to return a boolean value.

Verification request response field top-level fields

A verification request response MAY have an object field named headers, whose fields represent the HTTP headers.

A verification request response MAY have an object field named body, which is the HTTP response body.

The header value and body can be a JSONPath expression, the expression must be inside a placeholder ${ }.

To escape the expression, prefix it with an extra $ character, e.g. $${ }. See JSONPath for more information about JSONPath.

JSONata expression can also be used instead of JSONPath, prefix the expression with jsonata, e.g. ${jsonata: }. See JSONata for more information about JSONata.

Following variables are available:

Name

Type

Description

headers

Map

HTTP request headers

parameters

Map

Query parameters

Here is an example response to a verification request with a challenge parameter:

{
  "headers": {
    "X-Content-Type-Options": "nosniff",
    "Content-Type": "text/plain"
  },
  "body": "${parameters.challenge}"
}

Validate the payload field

The field MAY have a JavaScript expression and may be evaluated to return a boolean value. If the expression returns true, then the workflow will start. Otherwise response with 401 Unauthorized status code.

Following variables are accessible with $ identifier:

Name

Type

Description

headers

Map

HTTP request headers

parameters

Map

Query parameters

remoteAddress

String

IP address of the client that sent the request

body

String

HTTP request body as String

See also list of JavaScript expression functions.

Here is an example of payload validation to verify the authenticity of the request by looking at the x-signature header, which will contain the HMAC-SHA256 signature of the entire request body using a secret as the key:

Swf.hmacSha256Hex('secret', $.body) === $.headers['x-signature']

Here is another example of payload validation to only accept request from known IP ranges:

Swf.ipAddressMatches("82.115.214.0/24", $.remoteAddress) ||
  Swf.ipAddressMatches("185.66.202.0/23", $.remoteAddress) ||
  Swf.ipAddressMatches("185.237.4.0/22", $.remoteAddress)