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:
-
Log in to the SimWorkflow.
-
Navigate to Workflow definitions.
-
For a specific workflow definition, select the Webhook settings menu in the 3 dots dropdown menu.
-
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 |
|---|---|---|
|
|
Map |
HTTP request headers |
|
|
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 |
|---|---|---|
|
|
Map |
HTTP request headers |
|
|
Map |
Query parameters |
|
|
String |
IP address of the client that sent the request |
|
|
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)