Webhook

Load data from URL

With webhooks you can call an arbitrary URL from Ultradox to retrieve data from other services.

You can specify the URL, the request method (GET, POST, PUT, PATCH, DELETE or HEAD), the header fields and the authentication method.

If the result is provided in valid JSON or XML format, the returned data will parsed and can be accessed in subsequent building blocks or in your templates.

Use cases

Call 3rd party services from Ultradox

Configuration

Click on the bold name of the webhook in the building block title to open the configuration dialog.

Option	Description
Name	Enter the name of the webhook that will be displayed in the title of the building block.
URL	Enter the URL of the endpoint you want to call.
Headers	You may want to send header fields with your request. Header keys and values must be separated with a colon. If you want to pass multiple headers, separate them by a comma. Use variables to pass the desired data in your headers. Example: `X-PW-AccessToken:${pwAccessToken},X-PW-Application:developer_api`
Body	You can specify the request body if you are using the `POST` method to send the request. Use variables in your body to pass the desired data. See example below how to merge variables into your request body.
API definition	You may want to describe the API that you are calling so that the fields show up as variables in the auto-completion in Ultradox as well as in the template editor and email designer add-ons for Google Docs. See example b elore how to define the input and output of the invoked service.
URL of API definition	Optionally you can serve the definition of the API in the same format as above from your server. Just enter the URL that will return the API definition.

Body example

When selecting either POST , PUT or PATCH as method you can specify the request body to be sent to the service.

In the request body you can access all variables and formatting options to exactly specify the format that your server expects.

You may for example want to use the object renderer with output format of=json to serialize any objects in JSON format or use the string renderer with encding option encode=json to automatically encode your strings so that any special characters do not screw up the generated request body.

If you are sending data in json format, make sure to specify the content-type header by typing Content-Type:application/json into the header field

{
'email' : '${email}',
'message' : '${log;object(of=json)}'
}

{
"email" : "[email protected]",
"log" : {
"date" : "2012-11-04",
"level" : "INFO",
"message" : "Server error"
}
}

API definition example

The API definition is important to let Ultradox know how the retrieved data looks like.

Once you have defined the data the variables will appear in the condition builder and list building blocks so that you can work with.

Make sure to specify both input and output, even if no parameters are present

When recoding the output parameters the API definition will be generated for you as a starting point.

You can then adjust the generated API definition to your needs.

{
"input": [
{
"name": "minAge",
"prompt": "Enter the minimum age of the users:",
"description": "Minimum age",
"defaultValue": "21",
"format": "NUMBER"
}
],
"output": [
{
"name": "users[].name",
"description": "Contains the given name of the user",
"format": "STRING"
},
{
"name": "users[].age",
"description": "Contains the age of the user",
"format": "NUMBER"
},
{
"name": "maxAge",
"description": "Contains the age of the oldest user",
"format": "NUMBER"
}
]
}

Record parameters

It can take quite a while to define all the output variables, especially if you are receiving a lot of data with nested arrays and alike.

You can let Ultradox detect the output variables from the received data automatically by clicking on the record button in the main toolbar of the building block.

Once clicked the record button will turn red and start blinking to indicate that it is waiting for data. Click the button again to cancel record mode.

Now simply run your flow with the webhook armed. Ultradox will analyze the received data and will auto-generate the matching output variables.

Once the data has been recoded the execution of your flow will be aborted and the record button will turn black again.

The detected output variables will appear on the right. You can then open the configuration dialog again and adjust the auto-generated API definition.

Questions and Feedback

If you have any comments on this page, feel free to add suggestions right to the Google document that we are using to create this site.

If you are not yet member of the Ultradox community on Google+, please join now to get updates from our end or to provide feedback, bug reports or discuss with other users.

Last Updated: 7/7/20

Reference / Core / Webhook