Advanced Webhook

Configuration

The following properties are required for an advanced webhook.

Property	Description
Advanced Webhook URL	http(s)://<servername>/wfe/api/advancedwebhook/<advancedwebhookname> for the advanced webhook
Server Name	The name or IP address of your UIP server
Advanced Webhook Name	The case-sensitive name of the advanced webhook configured in a advanced webhook Trigger
HTTP Method	POST
Authentication Type	Basic
Credentials	The user name and password required to access the advanced webhook. The credential can be configured in the Workflow Settings page.
Content Type (Optional)	Properties can be passed to the trigger through query string, JSON data in the request body or URL encoded form data. For JSON data use Content Type: application/json For Form data use Content Type: application/x-www-form-urlencoded Other content types are not supported. If no request body data needs to be sent, leave content type empty.
Request Body (Optional)	If the content type is application/json then the request body must be valid JSON data. See Passing Properties for more information.

Invoking an Advanced Webhook

Invoking an advanced webhook can be done in two ways (this depends on the Response Type value set for the Advanced Webhook):

• As a regular webhook if the Response Type was set to None or Custom. This is a fire and forget invocation, meaning the advanced webhook will not wait for the workflow to complete before returning. To invoke it, a client application must issue an HTTP POST with the advanced webhook URL.
• As a waiting webhook if the Response Type was set to Workflow or Workflow Wrapper. This type of invocation will wait for the workflow to complete before returning. A client application must issue an HTTP POST with the advanced webhook URL.

The result of the call is returned with an HTTP status code:

Status Code	Text	Description
200	OK	The request was accepted. For the advanced webhook this will also be returned for the following cases: - Trigger condition failed - Workflow not found - Workflow canceled - Workflow returns failure - Workflow returns success
400	Bad Request	The request was not accepted for one of the following reasons: Content Type is not supported Content is in an invalid format or could not be parsed Missing Webhook Name in the URL Request body content is larger than 1MB
401	Unauthorized	Lacking authentication credentials or credentials are not accepted.
404	Not Found	The request was not accepted for one of the following reasons: Advanced Webhook Name was not found Trigger is disabled
500	Internal Server Error	An unspecified error occurred. For the advanced webhook this will also be returned when the workflow did not complete in time.

Note: For the non-waiting advanced webhook, no response data is returned if the status code is not 200 OK. For the waiting advanced webhook, the response will always contain data, see table below. If the workflow executes, the result will contain a property bag containing the workflow results. If a workflow error occurs (such as workflow not found, workflow canceled, trigger condition failed, timeout error, etc.), the response results will contain an error code and an error message describing what went wrong.

Response data (wait advanced webhook only)	Description
workflow	Name of the workflow that has been executed
status	Workflow execution result: 0: Success 1: Failed 2: Aborted
results	Property bag, containing the output values from the executed workflow

Note: You may have multiple advanced webhook triggers configured with the same URL. When calling a wait advanced webhook with such a URL, although all the triggers will be fired, only the result from the first fired trigger will be returned. To have consistent results it is advised to not have the same wait advanced webhook URL configured for more than one trigger.

Passing Properties

A client application can pass properties through the advanced webhook request to the trigger. There are 3 ways to pass properties:

• Through Query String in the URL
• Through JSON Data in the request body
• Through Form Data as URL encoded form data

Query String

To pass properties through the advanced webhook URL's query string, you must join keys and values with an equals-character (=). Multiple key/value pairs must be joined with an ampersand (&). Note that the keys and values need to be URL encoded (see https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding for details on URL encoding).

If properties are passed through the trigger as URL query strings and the same property is included in the JSON Data or Form Data, the trigger uses the JSON or Form Data.

To pass the following example properties:

Property Key	Property Value	Joined and URL encoded
name	John Doe	name=John%20Doe
id	a3b$-555/field	id=a3b%24-555%2Ffield

The syntax of the advanced webhook URL would then be in the following format:

http(s)://<servername>/wfe/api/advancedwebhook/<advancedwebhookname>?name=John%20Doe&id=a3b%24-555%2Ffield

JSON Data

Content from JSON can be used as input properties. To use that, pass the JSON data in the request body. The Workflow Engine will flatten and convert the data to trigger properties.

With the following example JSON request body:

{
  "Title": "Object Recognition",
  "DateTime": "2018-08-22T12:00:00Z",
  "Result": {
    "Status": "Success",
    "Objects": [
      "Dog",
      {
        "Human": {
          "Age": 20,
          "Beard": true,
          "Name": "John Doe"
        }
      }
    ]
  }
}

If the Advanced Webhook is configured with All Properties checked and Parse Body checked, the JSON will be flattened and converted to properties as follows:

Property Key	Property Value	Value Type
Title	Object Recognition	String
DateTime	2018-08-22T12:00:00Z	String
Result.Status	Success	String
Result.Objects[0]	Dog	String
Result.Objects[1].Human.Age	20	String
Result.Objects[1].Human.Beard	true	String
Result.Objects[1].Human.Name	John Doe	String
Result.Objects.count	2	String

For more information about JSON flattening, see JSON Flattening and Unflattening

Form data

To pass properties through the advanced webhook as form data the form data should include keys and values with an equals-character (=). Multiple key/value pairs must be joined with an ampersand (&). Note that the keys and values need to be URL encoded (see https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding for details on URL encoding).

To pass the following example properties:

Property Key	Property Value	Joined and URL encoded
name	John Doe	name=John%20Doe
id	a3b$-555/field	id=a3b%24-555%2Ffield

The syntax of the form data would then be in the following format:

"name=John%20Doe&id=a3b%24-555%2Ffield"