Webhook

Configuration

The following properties are required for a webhook.

Property	Description
Webhook/WaitWebhook URL	`http(s)://<servername>/wfe/api/webhook/<webhookname>` for the webhook `http(s)://<servername>/wfe/api/waitwebhook/<webhookname>` for the waiting webhook
Server Name	The name or IP address of your UIP server
Webhook Name	The case-sensitive name of the webhook configured in a webhook Trigger
HTTP Method	`POST`
Authentication Type	`Basic`
Credentials	The user name and password required to access the 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 a Webhook

Invoking a webhook can be done in two ways:

As a regular webhook. This is a fire and forget invocation, meaning the webhook will not wait for the workflow to complete before returning. To invoke it, a client application must issue an HTTP POST with the webhook URL.
As a waiting webhook. This type of invocation will wait for the workflow to complete before returning. A client application must issue an HTTP POST with the waiting 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 waiting 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: Webhook Name was not found Trigger is disabled
500	Internal Server Error	An unspecified error occurred. For the waiting webhook this will also be returned when the workflow did not complete in time.

Note: For the regular webhook, no response data is returned if the status code is not 200 OK. For the wait 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 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 webhook triggers configured with the same URL. When calling a wait 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 webhook URL configured for more than one trigger.

Passing Properties

A client application can pass properties through the 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 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 webhook URL would then be in the following format:

http(s)://<servername>/wfe/api/webhook/<webhookname>?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"
        }
      }
    ]
  }
}

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 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"