Skip to content

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 Integration Platform 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 Propery 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:

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"